CD Ware Multimedia 1995 May

home *** CD-ROM | disk | FTP | other *** search

/ CD Ware Multimedia 1995 May / cd Ware (Juegos) Epimundo.iso / DOS / UT_SYSTM / CLOCK_RS.ZIP / CLOCK.DOC < prev next >

Wrap

Text File | 1994-11-20 | 167.2 KB | 4,178 lines

CLOCK Version 3.70 November 20, 1994 Version 3.70 CLOCK is a shareware program. See Appendix A for registration information. $10 (or $25 for full source code) Ronald Q. Smith 11 Black Oak Road St. Paul, MN 55127-6204 Copyright 1991-1994 Ronald Q. Smith CLOCK Version 3.70 November 20, 1994 CONTENTS 1. INTRODUCTION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 1.1 Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 1.2 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 2. CLOCK.SYS - Replacement Device Driver . . . . . . . . . . . . . . . . . 7 2.1 Unique Clock Hardware Support . . . . . . . . . . . . . . . . . . 7 2.2 Installing CLOCK.SYS . . . . . . . . . . . . . . . . . . . . . . 8 2.3 Clock Type . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 2.4 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 2.5 Future Enhancements . . . . . . . . . . . . . . . . . . . . . . . 14 3. CLK.EXE - Clock Control Program . . . . . . . . . . . . . . . . . . . . 15 3.1 CLK Command . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 3.2 Using CLK with Windows . . . . . . . . . . . . . . . . . . . . . 24 3.3 Calculating the Adjustment Factor . . . . . . . . . . . . . . . . 24 3.4 Format of TZ= Function . . . . . . . . . . . . . . . . . . . . . 25 3.5 Using CLK . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 3.6 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 3.7 Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 3.8 Future Enhancements . . . . . . . . . . . . . . . . . . . . . . . 31 4. CLKDEMO.EXE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 4.1 CLKDEMO Command Line . . . . . . . . . . . . . . . . . . . . . . 32 5. IOCTL - API TO CLOCK.SYS . . . . . . . . . . . . . . . . . . . . . . . 33 5.1 Data Structures . . . . . . . . . . . . . . . . . . . . . . . . . 33 5.2 clksta . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36 5.3 setpw . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 5.4 connec . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 5.5 newpw . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 5.6 rstrct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42 5.7 stmode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 5.8 stzone . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45 5.9 tdisp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47 6. CLOCK.SYS - ASSEMBLY LANGUAGE API . . . . . . . . . . . . . . . . . . . 50 6.1 Opening the CLOCK$ Device . . . . . . . . . . . . . . . . . . . . 50 6.2 Sending New Values to CLOCK.SYS . . . . . . . . . . . . . . . . . 50 6.3 Getting Current Status of CLOCK.SYS . . . . . . . . . . . . . . . 51 APPENDIX A: DEFINITION OF SHAREWARE . . . . . . . . . . . . . . . . . . . 52 APPENDIX B: CLOCK TYPES . . . . . . . . . . . . . . . . . . . . . . . . . 54 B.1 Type 0 - PC/AT . . . . . . . . . . . . . . . . . . . . . . . . . 54 B.2 Type 1 - Zenith Z-18x portables, Supersport 20 . . . . . . . . . 54 B.3 Type 2 - Various Zenith Data System PCs. . . . . . . . . . . . . 55 B.4 Type 3 - Memory-Mapped Clocks . . . . . . . . . . . . . . . . . . 55 B.5 Type 4 - Direct Register I/O Bus Clock . . . . . . . . . . . . . 56 B.6 Type 5 - Mitsubishi 8088 PCs . . . . . . . . . . . . . . . . . . 58 B.7 Type 6 - Indirect Register I/O Bus Clock . . . . . . . . . . . . 59 B.8 Type 7 - Complex I/O Bus Clock . . . . . . . . . . . . . . . . . 59 B.9 Type 8 - Generic I/O Bus Clock . . . . . . . . . . . . . . . . . 60 2 CLOCK Version 3.70 November 20, 1994 B.10 Type 9 - Quadram I/O Bus Clock . . . . . . . . . . . . . . . . . 60 B.11 Type A - AT&T 6300, 6300 PLUS, 6300 WGS . . . . . . . . . . . . . 61 B.12 Type B - Hyundai 8088 Clock . . . . . . . . . . . . . . . . . . . 62 B.13 Type C - Multi I/O Card Clock . . . . . . . . . . . . . . . . . . 62 APPENDIX C: REVISION HISTORY . . . . . . . . . . . . . . . . . . . . . . . 64 3 CLOCK Version 3.70 November 20, 1994 1. INTRODUCTION 1.1 Definitions Your PC contains two clocks. One of these is referred to in this document and in messages from CLK as the "calendar clock." The other is referred to as the "DOS clock." CALENDAR CLOCK The calendar clock is the clock that retains the date and time when your system is turned off. It is the clock that requires a battery and for that reason is also called the battery-protected clock. Various hardware vendors also refer to it as the real-time clock, the CMOS clock, and the day clock. In most systems it is a bit of logic on the motherboard or other add-in board and consists of a clock chip, a battery, and some control logic. Some older clocks are on little mini-boards that plug into a cable (e.g., floppy cable) or socket under another chip. The calendar clock typically has a set of internal counters that maintain the seconds, minutes, hours, day of week, day of month, month, and year. Some don't allow you to set the seconds and can only be set on the minute even though they may allow you to read the seconds. Many of them don't maintain the year. They expect the software to simply keep the year up to date by writing it to the chip every time you boot. Some of the calendar clocks don't handle leap years. CLOCK.SYS will handle the leap years for you on those clocks. The calendar clock is normally read once when the system is booted and the time is then written to the DOS clock. The calendar clock is then normally never read again, but it is written if you change the time. Since the calendar clock is usually substantially more accurate than the DOS clock, one of the functions that CLOCK.SYS can perform for you is to periodically read the calendar clock and reset the DOS clock. DOS CLOCK The DOS clock is really not a clock although it is used like one. It is really just a counter that increments at a known rate (18.2 times per second). The DOS clock is also called the BIOS clock, the interval timer, and the incrementing counter. When you boot the system, your clock driver software (CLOCK.SYS, the driver built into DOS, or another add-in software driver) reads the calendar clock and converts the date and time to the number of days since January 1, 1980, and the number of seconds since midnight on the current day. The number of days is just saved inside the clock driver. The number of seconds is converted to a number of counter ticks using a little more exact number than 18.2. The number of ticks is then stored in the counter by calling the BIOS. When you ask DOS to read the clock, it calls the clock driver which reads the counter by calling the BIOS, converts the number of ticks back to seconds, and returns the number of days that it has saved and the number 4 CLOCK Version 3.70 November 20, 1994 of seconds to DOS. The BIOS checks to see if the counter goes past midnight. If it does, it resets the counter to zero and tells the next caller that the day has advanced. In that case the clock driver increments the day that is has saved before returning it to DOS. Unfortunately, the BIOS only tells the first caller after midnight that the day has advanced. That is the common reason for the day not advancing on your PC when you leave an application running over midnight. Many applications use the BIOS counter internally just to get interval timing information. When they do, DOS doesn't see that the day has advanced. This is another problem that CLOCK.SYS solves. It checks to see if the time ever appears to run backwards and increments the day if it does. 1.2 Overview CLOCK consists of two programs that give you complete control over the operation of your calendar (battery-protected) clock and your DOS/BIOS internal timer. The normal DOS mode of operation is to read the calendar clock when you boot the system and set the internal timer. Thereafter all read operations refer only to the internal timer while time setting operations write to both clocks. In levels of DOS prior to 3.3, even time setting opera- tions only wrote to the internal timer. In order to set the calendar clock you had to run the SETUP program. Some of the drawbacks to the standard DOS clock operation that the CLOCK programs address are: There is no provision to switch time zones without resetting the system time. DOS does not handle automatic changes between daylight savings time and standard time. The DOS/BIOS internal timer often drifts quite rapidly away from the time maintained by the more accurate calendar clock. Even the calendar clock drifts slowly away from the accurate time. DOS provides no way to automatically adjust for that drift. If your battery is failing or some other hardware or software problem messes up the time in your calendar clock, there is no way to detect that except by manually displaying the time and checking it. If you have to run a program that occasionally changes the time incorrectly, there is no way to protect your clock from those changes. You can also have this problem if you are a parent whose children set the clock when you don't want them to, an instructor whose students reset the time, or an expert young user whose parents mess up your clock. If you need to experiment with special times and dates but don't want to have to reset your clock afterwards, DOS has no mechanism to h e l p. In order to test end-of-month processing for your 5 CLOCK Version 3.70 November 20, 1994 application, you have to set the date and time, run your tests, and then set the time and date back. The standard DOS and BIOS software on some PCs can miss the change to a new day when the PC is left on over midnight. Your clock might not handle automatic changes to a new year or may not understand leap years. You may have an older PC from before the PC/AT clock standardization and your vendor no longer releases new versions of DOS for that PC. You are stuck on DOS 3.2 or earlier or you have to give up your calendar clock. If any of those circumstances cause problems for you, CLOCK can help. The two primary programs are CLOCK.SYS and CLK.EXE. In addition, if you are a software developer, CLKDEMO is provided in source code to show you how to program the extended clock operations into your own applications. CLOCK.SYS is a clock device driver (CLOCK$ device). It replaces the DOS internal clock driver. CLOCK.SYS provides for automatic time zone conversion. It also allows you to periodically or continuously get the time from the calendar clock. This can totally eliminate problems with missing day changes and realtime clocks that are inaccurate. CLOCK.SYS provides support for many types of calendar clocks including many of the original add-in clocks of the 8088 era. If your clock is not currently supported, I want to hear from you. I will be happy to add it to the software. CLK.EXE is a program that allows you to separately control your DOS/BIOS internal clock and battery-protected calendar clock. Most importantly, CLK.EXE will handle time zones and will automatically switch between standard and daylight savings time for you. It also supports automatic adjustment for calendar clock drift, checks for incorrect or unlikely times, and can restrict time changes. CLKDEMO.EXE is a small part of CLK.EXE that is provided in source code (C language) form so that you can see how to add clock control to your own applications. 6 CLOCK Version 3.70 November 20, 1994 2. CLOCK.SYS - Replacement Device Driver CLOCK.SYS is a device driver that replaces the built-in CLOCK$ device driver in DOS levels 2.1 and above. CLOCK.SYS adds many functions not provided in the standard DOS CLOCK$ device driver. You won't see mention of the DOS CLOCK$ device driver in your DOS user's guides. You will see a very small mention of it in the system's programmers reference manuals if you are an assembly language developer. It is there and DOS was specifically designed to let you replace it with one of your own even if the manual doesn't tell you that. 2.1 Unique Clock Hardware Support CLOCK.SYS was originally written especially for those people whose clocks are not supported by new levels of DOS. This usually occurs because your vendor stopped providing new levels of DOS adapted for your computer model. Before the days of the PC/AT and standard clock interfaces, DOS was usually sold directly to hardware vendors who customized it for their system and delivered it with the system. In addition, many of the early clocks were provided by third-party, after-market vendors who had no idea what system it would be used in. Since those systems and clocks have been out of production for a long time, most of the vendors have stopped providing upgrades. Yet most of those PCs will happily run DOS 3.3 or above and especially DOS 5.0 except that you have to give up your calendar clock. CLOCK.SYS supports a wide variety of different clock hardware and BIOS interfaces. As far as possible, CLOCK.SYS will automatically determine what clock interface to use. If the automatic determination does not work for your system, you may tell CLOCK.SYS specifically what interface type to use. CLOCK.SYS is also required by anyone who wants to use CLK as it provides functions not provided by the normal DOS CLOCK$ device driver. CLOCK.SYS is fully compatible with the DOS device driver on all modern PCs and many older ones. If your PC clock is not currently supported but you would like to remove the restrictions on what versions of DOS you can use, please contact me by mail or on CompuServe. I will be happy to add support for your clock. I will need some technical information and help from you in getting it to work so I will give you a $0 usage license for your help. Please see section 2.3 for the current list of supported clocks and Appendix B for a description of those clocks. 7 CLOCK Version 3.70 November 20, 1994 2.2 Installing CLOCK.SYS To install the device driver include the following line in your CONFIG.SYS file. Syntax device=[d:][path\]clock.sys [type][,io_addr] [/N] or device=[d:][path\]clock.sys 3[,segment[,write0, write1,read]] [/N] or device=[d:][path\]clock.sys A[,base_year] [/N] Parameters d: Identifies the drive containing CLOCK.SYS. If d: is not provided, the boot drive is assumed. path\ Specifies the directory containing CLOCK.SYS. If path\ is not given, the root directory is assumed. CLOCK.SYS Is the name of the CLOCK.SYS file. You may change the name if you wish, but you must not use the .COM or .EXE extensions. type Is the kind of calendar clock on your system. If you do not provide type, CLOCK.SYS will probe your system to determine which clock you have. CLOCK.SYS is usually able to detect the type of calendar clock without trouble. It is possible, however, that you have some other hardware in your system that could fool CLOCK.SYS. For that reason, you might need to pro- vide the type of clock. See section 2.3 and Appendix B for more information about the clock types. io_addr Is the I/O bus address of your clock hardware. Some of the types of clocks that are supported were set up at a wide variety of I/O addresses. CLOCK.SYS probes all the commonly used I/O addresses for these clocks. However, you or your vendor may have installed your clock at an address that CLOCK.SYS doesn't know about. By providing the address, you make it much more likely that CLOCK.SYS will correctly find your clock. Even if you don't know what type of clock you have, providing the I/O address may be enough for CLOCK.SYS to determine which one it is. io_addr is currently used with clock types 4, 6, 7, 8, 9, B, and C. Normally this is 240, 2C0, or 340 for types 4, 6, and 7. It is 210 or 310 for type 9. It is E0 for type B. And, it is 338 for type C. All numbers are in hex. For example, an AST Research clock might 8 CLOCK Version 3.70 November 20, 1994 be: device=[d:][path\]clock.sys 4,2C0 If you do not specify the "io_addr", CLOCK.SYS will try to determine the correct address by probing. If you are sure that you have an I/O clock but you are not sure which one it is, specify type 8 and supply the io_addr if possible. Type 8 does not represent a specific clock. Rather it attempts to determine whether your clock is a type 4, 6, 7, 9, or B using a sequence of tests similar to those used by some of the I/O clock vendors to figure out what kind of clock you have. If you have a memory mapped clock, you may use the second format to specify the addresses to be used. If you don't know the addresses, CLOCK.SYS will attempt to determine them by probing. segment Is the base address used to access the clock. Usually your documentation will give the segment address as four hex digits such as FE00 or F000. Some addresses may be less than four digits (e.g., 70). Other documentation may show addresses in the form aaaa:bbbb. In this case the segment address is the aaaa value. Sometimes these addresses are written as 0xaaaa, aaaah, aaaaH, or 0Xaaaa. In all of these forms there is a 2- to 4-digit hex number that is the segment address. write0 Is the offset used to write 0 bits. It must also be a hex address and may be 0, F002, or anything else the vendor chose. If the addresses are given in the aaaa:bbbb form, use the bbbb. With these clocks, you read and write the clock by reading the memory addresses. For example, reading address segment:write0 results in writing a zero bit to the clock. Writing an ap- propriate length sequence of zero and one bits sets the clock. write1 Is the offset used to write 1 bits. read Is the offset used to read bits. If your documentation gives the segment address but isn't clear about the offsets, just specify the segment address and CLOCK.SYS will try all offset combinations that it knows about. If you specify one of the offsets, you must specify them all. 9 CLOCK Version 3.70 November 20, 1994 The third format is used with the AT&T 6300 clocks. base_year Is used for the AT&T 6300 clocks (type=A). Dates prior to that year or more than 7 years after that year will not be handled correctly. If no base year is specified, 1992 will be used. Dates between the start of the base year and the end of the s e v e nth year later are handled (e.g., 1992-1-1 until 1999-12-31). /N Indicates that you do not want CLOCK.SYS to attempt to detect missed date changes. Normally CLOCK.SYS will try to detect when a date has changed that was not reported by the BIOS. This usually happens when a program is running past midnight and calls the BIOS to read the time rather than calling DOS. That program sees the date-change indication from the BIOS and DOS (CLOCK.SYS) never gets a chance to change the day. However, the logic that CLOCK.SYS uses can be fooled by programs that change the time with direct calls on the BIOS and may advance the date incorrectly. This is very rare, but if your date advances unexpectedly or by more than one day, you may want to use this option. Notes DOS interfaces All DOS DATE and TIME commands and all DOS date and time system calls will operate with no apparent change to you or any program. Unless you have used CLK to change the time handling, your clocks are handled just as DOS would handle them. Dates and leap years CLOCK.SYS supports all valid DOS dates from 1980-1-1 to 2079-12-31. It supports dates to 2099-12-31 for many of the clocks. CLOCK.SYS also handles year changes and leap years automatically for clock types that don't do it themselves. Time zones and daylight savings time CLOCK.SYS in conjunction with CLK.EXE provides support for multiple time zones and automatic conversion between daylight savings time and standard time at the appropriate times of the year. For this reason, CLOCK.SYS may be of great use to you even if your version of DOS already supports your clock correctly. Clock synchronization Normally, CLOCK.SYS operates identically to the DOS CLOCK$ device driver. At boot it sets the DOS clock from the calendar clock. Any time you change the date or time it writes to both clocks. With CLK.EXE you have several other options. If you have specified a time zone and offset with CLK.EXE, CLOCK.SYS will adjust all times read from and written to the calendar clock by the time zone offset. You can also set it to read the calendar clock rather than the DOS c l o c k for some or all time requests to ensure continued synchronization of the two clocks. You can also totally separate the two clocks so that DOS time and date functions only read and 10 CLOCK Version 3.70 November 20, 1994 write the DOS/BIOS internal clock. Time setting limits CLK.EXE can tell CLOCK.SYS to apply limits to the time changes that it will accept or stop accepting time changes at all. For example, you can tell CLOCK.SYS to accept no changes that would set the clock backward. You can also inhibit all changes. Password Protection CLK.EXE can establish a password to control future changes to the time zone, connection, and time setting limits. Once the password is set, all attempts to change those values will simply be ignored unless the correct password is supplied. You may change the daylight versus standard time flag and the continuous time display without knowing the password. Continuous Time Display CLK.EXE can tell CLOCK.SYS to display the date and time continuously at any position on your screen. You specify the cursor coordinates, display attributes, and 12-hour or 24-hour mode and CLOCK.SYS will update the display every second. The date display is optional. Saving Settings Across Boots With CLK.EXE you can save the current state of CLOCK.SYS at any time in a form that can be used on your next boot. You can set up your time zone, setting limits, connection mode, continuous display, and password and then save a new version of CLOCK.SYS. This new version will automatically start running with without having to scan for your clock type and with all your standard state automatically in effect. 2.3 Clock Type There are almost as many different implementations of PC clocks as there are different types of PCs. Until the PC/AT came along, there was no standard for battery-protected clocks, and each PC and add-in vendor was likely to implement them differently. With the PC/AT a standard and documented interface for such clocks was provided. Since that time, most PCs have followed the PC/AT standard. It is earlier PCs, especially 8088 PCs, that don't follow the standard. Since these are early PCs, there is also a high probability that the vendor is no longer providing modified versions of DOS with built-in support for their clocks. Most add-in clock vendors never did provide a modified DOS and you had to manage your clock with utility programs. This leaves you faced with the choice between staying with an early version of DOS or giving up your clock. CLOCK.SYS is intended to free you from those limitations. It will work with all versions of DOS from 2.10 through 6.20 and undoubtedly beyond. It also attempts to automatically determine what kind of clock you have and install the correct support for it. However, there are often enough differences between PCs that the automatic determination may not find anything or may even make the wrong choice. To give you more control of the situation, you may specify the clock interface by giving an interface number. It will not always be easy to decide what interface number to use. You will 11 CLOCK Version 3.70 November 20, 1994 at least need some technical information on how your clock works or on the BIOS calls used to control the battery-protected clock. If you find a description below that seems to match, give it a try. The most that should go wrong is that your time and date will be set incorrectly, but then they proba- bly weren't working anyhow. If you aren't sure what interface to use or if you are sure that your clock is not supported, LET ME KNOW. I WOULD LIKE TO HELP. You can help me make CLOCK.SYS better for everyone. I would even like to hear from you if CLOCK.SYS did work for you and your clock isn't currently listed. I would like to be able to add your PC manufacturer and model number to the supported list so others know what to use. If CLOCK.SYS did not work for you, I am interested in making the changes so that it does work. If you can provide me with the necessary technical information, I will make the changes. Usually, a technical reference manual with hardware and BIOS interfaces is the best source. Even if you don't have one, your original hardware vendor may be willing to send you enough information to allow you to program the clock. If all else fails, we may even be able to use an old copy of DOS or a clock setting utility to figure out how it works. Before we do that, check your license to be sure that it is not forbidden to disassemble the software to see how the clock works. The following table shows the systems that have been determined to work with existing clock types. If your system is in the list, try the clock type indicated. If not, look through Appendix B which tells you about the charac- teristics of each type of clock and see if anything seems to match your system type. 12 CLOCK Version 3.70 November 20, 1994 ╔═══════════════════════════╤══════════════════════════╗ ║ SYSTEM │ CLOCK TYPE ║ ╟───────────────────────────┼──────────────────────────╢ ║ Amstrad PC1521DD │ 0 ║ ╟───────────────────────────┼──────────────────────────╢ ║ AST Research │ 8 (4, 6, or 7) See dis- ║ ║ Six-Pack │ cussion above and in ║ ║ I/O Plus │ Appendix B ║ ║ etc. │ ║ ╟───────────────────────────┼──────────────────────────╢ ║ AT&T 6300 │ A ║ ╟───────────────────────────┼──────────────────────────╢ ║ Hyundai 8088 │ B ║ ╟───────────────────────────┼──────────────────────────╢ ║ IBM PC/AT and most │ 0 ║ ║ PCs since then. │ ║ ╟───────────────────────────┼──────────────────────────╢ ║ Leading Edge Model D │ 5 ║ ╟───────────────────────────┼──────────────────────────╢ ║ Mitsubishi 8088 │ 5 ║ ╟───────────────────────────┼──────────────────────────╢ ║ Multi I/O Card │ C ║ ╟───────────────────────────┼──────────────────────────╢ ║ NEC MultiSpeed │ 0 ║ ╟───────────────────────────┼──────────────────────────╢ ║ Quadram Corp. │ 9 ║ ║ QuadCard │ ║ ║ QuadCard II │ ║ ║ QuadCard 512+ │ ║ ╟───────────────────────────┼──────────────────────────╢ ║ SMT No-Slot Clock │ 3 ║ ╟───────────────────────────┼──────────────────────────╢ ║ Sperry PC-1 │ 5 ║ ╟───────────────────────────┼──────────────────────────╢ ║ Sperry PC/HT │ 5 ║ ╟───────────────────────────┼──────────────────────────╢ ║ Tandy 1200HD │ 4 ║ ╟───────────────────────────┼──────────────────────────╢ ║ Vendex Turbo-888-XT │ 4 ║ ╟───────────────────────────┼──────────────────────────╢ ║ Zenith Supersport 20 │ 1 ║ ╟───────────────────────────┼──────────────────────────╢ ║ Zenith Z-18x │ 1 ║ ╚═══════════════════════════╧══════════════════════════╝ 2.4 Examples For almost everyone, the only format you ever need to use is: device=[d:][path\]clock.sys If CLOCK.SYS is in the root directory of your boot device, this is: device=clock.sys 13 CLOCK Version 3.70 November 20, 1994 CLOCK.SYS will quite happily load into the upper memory blocks (UMBs) provided by DOS 5.0 and by other software. With DOS 5.0, you might use: devicehigh=clock.sys With some memory managers you can even load CLOCK.SYS into upper memory blocks on earlier levels of DOS. See your manual for the commands to use. Some of these memory managers will create UMBs on 8088 and 80286 systems. CLOCK.SYS loads and runs high on those systems as well. With a memory mapped clock that uses an address combination that CLOCK.SYS doesn't search automatically and with CLOCK.SYS stored in the C:\UTILITY di- rectory, you might use: device=c:\utility\clock.sys 3,ffff,f000,f004,f008 Please note that the memory addresses chosen for this example are not likely to match those of your clock and you should substitute the addresses appropriate to your clock. If you have an I/O clock with the same interface as the Quadram Corp. clock but a different I/O address, you might use: device=clock.sys 9,3fc if your I/O base address were 3fc. If you have one of the AT&T 6300 system types and you occasionally need to set your clock prior to 1992-1-1, you might use: device=clock.sys a,1988 2.5 Future Enhancements Of course, I hope to add more clocks as people ask for them. Those old PCs are still good for a lot of what we do even if they are sometimes relegated to a secondary status. There are no other outstanding enhancements currently planned for CLOCK.SYS. 14 CLOCK Version 3.70 November 20, 1994 3. CLK.EXE - Clock Control Program CLK gives you complete control over the operation of the calendar clock and DOS/BIOS clock. You can operate them separately or together. You can estab- lish time zones, daylight savings time rules, automatic adjustment, synchroni- zation rules, and more. 3.1 CLK Command Syntax clk [function] [function ...] [/I[file]] [/?] or in full form clk [A=±sss.cc] [C=A|D|R|W] [D=[N][x,y,a[,[12|24][,D]]] [L=...] [M=...] [R=A|B-hh:mm:ss|F+hh:mm:ss|N|R] [S=C|D] [TZ=...] [W=-back,+forward] [/B] [/I[file][,C]] [/M[file][,C]] [/P[N]] [/S[file]] [/?] Parameters function There are many functions that may be used with CLK.EXE and they are discussed in the following paragraphs. You may use any number of functions on a single command line and they will be processed in the order in which you enter them. However, if any error is discovered in any of the functions, none of them are processed. Thus, clk c=r tz=:est is the same as the two command lines: clk c=r clk tz=:est except that an error in either of the functions in the first example cause the whole command to be ignored. The case (upper or lower) of any of the function names, options, or values is ignored except for the TZ function's time zone names. Even there, the case is not used. It is simply preserved for later display. You can display a help message about any function or option by immediately following the function letter or option letter with ?. Thus M? displays help about the M= function and /I? displays help about the I option. /? displays a help message about the CLK command line. none If no function or option is provided, CLK displays the current state of operation of CLOCK.SYS and the current time from both the calendar clock and the DOS/BIOS clock. If you have used CLK to set a time zone (TZ function), the current time zone name and offset value are displayed. These values are saved in CLOCK.SYS so that they may be used for time functions. The connection state of the clocks (C function) is displayed as 15 CLOCK Version 3.70 November 20, 1994 is the current restrictions (R function) on clock changes. All uses of CLK (except errors and /?) end by displaying the same information. You always know the state of your two clocks after execution. A=±sss.cc or A=M The Adjust function is used to set a daily adjustment factor in seconds and 100ths of seconds. This function assumes that you have some knowledge of the rate at which your calendar clock drifts with respect to "real" time. Presumably you have periodically set your clock using a program that calls the Naval Observatory or NIST and noted the difference over time. Some such programs will help you to calculate the drift rate. You can get a very good adjustment from a decent quartz watch. The value may be a positive or negative number in the range - 326.99 to +326.99 seconds per day but reasonable values are likely to be a fraction of a second. The first time you use A=, your clock is not adjusted. The value of A and the current time are saved in a file for later use. Later you can choose to run CLK with the /I option to invoke the file. The elapsed time since the last adjustment (or the time you last changed A) in days and fractions is multiplied by A to calculate any adjustment that needs to be applied. Only whole seconds of adjustment are applied. The A= function only sets the adjustment factor. The actual adjustment is carried out by the L= function. You don't have to enter the L= function. CLK will do that for you the first time you use A= and will keep it up to date as it later makes adjustments. If you have been calculating a new adjustment with the M= function, you can apply the new calculated value by specifying A=M on the command line. We don't automatically apply the new calculated value until you use the A= function because we don't know when you are satisfied with the calculation. NOTE: Do not use the A= function with the AT&T 6300 clocks (Type A) or the Quadram clocks (Type 9). They only permit the time to be set to the nearest minute. C=A Connects the two clocks for All operations. All read operations go directly to the calendar clock. The calendard clock is read, the time is adjusted for any time zone offset, and the adjusted time is written to the DOS clock and returned to the caller. With this function, your calendar clock es- sentially becomes the only clock. However, the DOS clock is 16 CLOCK Version 3.70 November 20, 1994 set each time so that any application reading the clock di- rectly (without going through DOS) sees the same time that DOS reports. It is unwise to use this function if your clock is slow (some I/O clocks and some memory-mapped clocks) or if it only increments in units of seconds (most clocks). Any time zone offset is applied to reads and writes. C=D Disconnects the two clocks. Any change of the date and time will affect the DOS clock only. Reads also use the DOS clock only. This function allows you to perform any operation on the time without affecting your calendar clock. It is useful for dealing with ill-behaved programs that need to change the time and for testing programs at different dates and times. You can later use the C=R, C=A, or other functions to re-establish the value in your DOS clock from the calendar clock. C=R Connects the two clocks for writing and periodic Reading. This function may be used when your clocks drift slowly with respect to each other. If the time has not been read for about 10 sec- onds, the calendar clock will be read, adjusted by the offset if any, and the adjusted time written to the DOS clock and re- turned to the caller. This periodic Read assures you that the clocks never get very far out of synchronization with each other. Some calendar clocks take a relatively long time to read and most don't have 100ths of seconds. By only reading the calendar clock when no other time request has occurred in the last 10 seconds, we minimize both the overhead and any visibility of time jumps. C=W Connects the two clocks for Writing. This is the default mode of operation and is the same mode that the DOS CLOCK$ device driver supports as its only mode. Reading the time is served by the DOS clock. Writing the time sets both clocks. If a time zone offset has previously been specified, all writes to the clock are adjusted so that the calendar clock remains on the base time. For example, if the calendar clock is set to UTC and you specify that you want to use CST which has an offset of 6 hours from UTC, all writes of the time will have 6 hours added to them before writing to the calendar clock. Thus the DOS clock and the calendar clock remain at a constant time offset. D=N The D= function controls a continuous time display. D=N turns off the continuous display. D=x,y,a[,[12|24][,D]] Starts a continuous time display at cursor position x,y with display attribute a. Cursor position 0,0 is the upper left corner of the screen. The typical screen format runs from 0,0 to 79,24. The display attribute is a two-digit hex number that gives the background and foreground colors. The high-order 17 CLOCK Version 3.70 November 20, 1994 digit is the background color (0 to 7 usually) and the low- order digit is the foreground or character color (0 to F). The default display is a 24-hour clock in the form HH:MM:SS. If you add the ",12", the display will use a 12-hour clock. No AM or PM indication is given. If you add a D option after the time selection, the date is displayed in YY-MM-DD format in front of the time. D=63,24,79,12,d will place the display at the right edge of the last line of most screens. The text will be in bright blue on a white background and the hours will run from 12 through 11. D= by itself will resume a previous display that was turned off by D=N. You do not have to re-enter all the values. The D= functions should not be used if CLK is executed from within Windows. If you try to do so, you will received an error message. This avoids a hung system which would otherwise occur as Windows will not support programs which change interrupt vectors. L=YYYY-MM-DD,hh:mm:ss,±sss.cc The L= function is not intended to be used on the command line, but will be accepted if you provide it. The L= function is normally created by CLK and saved in the CLK.INI file for later use in processing adjustments. The date and time of the last adjustment (or the most recent time you gave an A= function on the command line) are given by the YYYY-MM-DD,hh:mm:ss. Any non-digit except a space may separate the sub-fields. The date and time must be followed by a comma and any adjustment remainder. The adjustment remainder is in the same form as the value for the A= function but will usually be a fraction of a second. It is the adjustment that was left over the last time an adjustment was actually made since only whole seconds of changes are made to the clock. The L= function triggers an adjustment if needed. Generally, it will follow the A= function that sets the adjustment factor. Both of these functions normally appear in the CLK.INI file. The L= function may also be used by itself to do simple arithmetic on the clocks. Use it on the command line with any earlier date and time and an adjustment of the number of seconds (positive or negative) that you want added to the clock. The change will be made and the last adjustment time set to the current time. For example, clk l=1990-1-1,0:0:0,-4 will subtract 4 seconds from the clocks. M=±sss.cc,YYYY-MM-DD,hh:mm:ss or M=LAST The M= function is used to help you calculate the automatic adjustment A= value for your calendar clock. The M= function 18 CLOCK Version 3.70 November 20, 1994 is used to enter the manual adjustments that you make to the clock in addition to the automatic adjustments. The ±sss.cc is the amount of manual adjustment that you have made. This may be adjustments made by setting the clock with the DOS DATE and TIME commands or adjustments made by a time setting program. The YYYY-MM-DD,hh:mm:ss is the date and time at which the adjustment was made. It is very important that the date and time be given with respect to the calendar clock and not the DOS clock, if different. If you do not supply the date and time, the current date and time will be used. This should be s u fficiently accurate if you just completed making the adjustement. M=LAST is the easiest way to input the changes and the time of last change. Whenever you set a new date or time, CLOCK.SYS saves the time immediately before setting the new value and the new value. M=LAST uses those two values to calculate the M= function for you. This even works if you are using a program to dial a time source. The first M= value that you enter is used only to set a base date and time. Then as you enter additional values in the future, CLK will calculate a new value for the A= function by adding the average manual adjustment per day to the current A= value. Up to 8 values are saved in the CLK.INI file (or other file that you specify). The more values you provide and the longer the time period, the more accurate the adjustment will be. For example, if you can only determine the adjustment to the nearest second (likely), you may want to have a week or more between manual adjustments. The only restriction is that the first and last manual adjustement must be within one year of each other. If you enter more than 8, the oldest two adjustement values are collapsed into a single value. Supplying a new A= value, presumably based on the calculations from CLK, deletes all the M= values from the file. You may either specify a /I option to specify the file and read all the functions in the file, a /M option to specify the file and only read the M= functions, or CLK will automatically specify the /M option for you (but it will only know to look for CLK.INI in the directory containing CLK.EXE). You may also edit the M= functions in the file and use the /M option to force a re- calculation. When CLK calculates a new adjustment value, it tries to determine if any of the M= values are out of line with the rest of the values. It will ignore, but provide an error message, if any of the values are too far away from all of the others. CLK calculates an average and standard deviation and ignores all values (of adjustment per day) that are more than 2 standard deviations from the average. 19 CLOCK Version 3.70 November 20, 1994 R=A The R= function sets restrictions on time changes. R=A inhibits All time changes. When this mode is set, all attempts to change the time are ignored by CLOCK.SYS. This includes time changes attempted by CLK including time adjustments. See R=N. R=B-hh:mm:ss This function limits the amount of Backward change of the time. Any change of more than the specified time is ignored. The "-" is optional as are the offset fields. clk r=b inhibits all backward changes. CLK R=B::2 only allows backward changes of two seconds or less This might permit CLK to perform adjustments but effectively stop other backward changes. R=F+hh:mm:ss This function limits the amount of Forward change of the time. Any change of more than the specified time is ignored. The "+" is optional as are the offset fields. CLK R=F+1:00:02 limits forward changes to 1 hour and 2 seconds. The R=B and R=F limits do not apply to the automatic conversions between standard and daylight savings time as these don't actually change the time. The R=B and R=F functions are also indepen- dent of the R=A function. R=N This function reverses the R=A function and inhibits No clock changes. The R=A is independent of the R=B and R=F. You can set backward and forward limits with R=B and R=F. Later you can inhibit all changes with R=A. When you do R=N, the previ- ously set R=B and R=F limits again have an effect. R=R This function Resets the limits established by R=B and R=F. No limits are in effect after executing this function. It has no effect on the R=A mode. S=C Sets both clocks to the current time from the calendar clock. You can use this even if the clocks are disconnected to make the DOS clock equal to the calendar clock. The time zone offset is set to 00:00:00 and the time zone name is set to UTC to indicate that both clocks are set to the base time. S=D Sets both clocks to the current time from the DOS clock. The value from the DOS clock is written to the calendar clock. The time zone offset is set to 00:00:00 and the zone name is not changed to indicate that both clocks are set to your local time. 20 CLOCK Version 3.70 November 20, 1994 TZ=... Sets the DOS clock to the correct local time based on the value of the expression following the TZ=. This expression conforms exactly to the POSIX 1003.1 standard for time zone handling. CLK assumes that the calendar clock currently contains UTC (also known as GMT, Greenwich, ZULU, and Z time). UTC ("Universal Time, Coordinated" is usually spoken as "coordinated universal time") is the name of the international standard time that is provided by WWV, WWVH, the Naval Observatory, and NIST as well as many other services around the world. Most Unix systems also support TZ although many only partially support the POSIX standard. See the notes later for a complete description of the TZ= function. You can put the CLK TZ=... command in your AUTOEXEC.BAT file. You should put it prior to any other statements that may create or update files or you run the risk of having confusing times in your file directory (MAKE could get especially confused.). If you provide a TZ= function, your system will automatically adjust to the correct time zone every time you boot. Note that no attempt is made to change between daylight and standard time except when you execute CLK TZ=... Adjusting on the fly is very dangerous. Many programs can produce incorrect results or even corrupt your data if time takes a big step forward and are even more likely to do so if time runs backward. See section 3.4, 3.4 for a discussion of the TZ= format. W=-back,+forward The W= function is used to establish Warning limits on the time. Each time the W= function is processed (usually from the CLK.INI file), the current time and the previous time are compared. If the current time is outside the -back,+forward range around the previous time, a warning message is displayed requiring you to press a key. The program will also exit with an ERRORLEVEL of 1. The full form of the W= function is: W=N-days/hh:mm:ss,+days/hh:mm:ss, YYYY-MM-DD,hh:mm:ss The days sub-field is a value from 0 to 250 days. The days sub-field combined with the time sub-fields gives the maximum interval around the previous time within which the current time must fall. The previous date and time follow the second comma. For example, clk w=-0/00:00:02,+91 will establish a range of minus two seconds to plus 91 days. The first time you use this function nothing will happen except that CLK will add the current date and time to the command and store it in the CLK.INI file. The next time you use if from the CLK.INI file with CLK /I, the current date and time will be compared to the previous date and time and the range. If the current time is outside the range, a message is displayed and CLK pauses. The sign characters and all of the sub-fields are optional. 21 CLOCK Version 3.70 November 20, 1994 Missing sub-fields are treated as zero. The particular separators are not important except for the commas. Any non- digit character can be used for the other separators. The time and date fields are appended to the function by CLK when the CLK.INI file is written and are the previous time to which the next comparison will be made. A typical function might be W=,31. This command will display a warning whenever time has moved backwards at all or has moved forwards by more than 31 days since the last time you used CLK /I. If you use CLK /I (see below) in your AUTOEXEC.BAT file, this is very likely to detect a miss-set clock or bad clock battery. Yet it won't generate a message on every boot. You will only get an "unnecessary" message if it has been more than a month since you last used the PC. If the "N" character (or "n") appears immediately after the "=", CLK does not pause and wait for you to press a key after printing the warning message. The "N" allows you to use CLK in a .BAT file and check for the warning with the IF ERRORLEVEL command. /B The B option tells CLK to remain in command mode even if no other functions or options are present. The /B in itself performs no operation, but it avoids CLK going into full-screen mode if all you want to do is display the current status (e.g., in a .BAT file). /I[,C] or /Ifile[,C] The I option tells CLK to read the CLK.INI file (or "file" if that is given) for additional functions. These functions are usually A=, L=, and W= functions that were previously written to the file by CLK. You may add any other functions (but no options) to the file and they will be processed as if you had entered them at the end of the command line. If you don't specify "file" or you don't give a path as part of "file", CLK will use the directory which contains CLK.EXE. Thus the de- fault is to use CLK.INI in the directory that contains CLK.EXE. If you enter an A=, L=, M=, or W= function or CLK finds them in the file, the file will be updated with the new values for the current time when appropriate. If an adjustment is made, the L= function will reflect the date and time of the latest adjustment. CLK will update or create a CLK.INI file even if you don't use the /I option if you use the A=, L=, M=, or W= functions on the command line. It is very useful to store your standard TZ=, C=, and R= functions in the CLK.INI file. Then your AUTOEXEC.BAT file can simply contain a CLK /I command to set your clocks into their standard modes, adjust the time, and check for bad clock values. You can also reestablish your standard modes after 22 CLOCK Version 3.70 November 20, 1994 changes with the same command entered from the DOS prompt or a .BAT file. The file may be hidden and still be updated without error. However, to update a read-only file, you must add ,C to the end of the option. This indicates that CLK may Change the attributes of the file in order to update it. CLK will restore the original attributes. System files may not be updated. /M[,C] or /Mfile[,C] The M option is identical to the I option except that only the M= function lines are read from the file. Its primary use is internal to CLK when processing an M= function from the command line. You may also use /Mfile to specify the location of the file when entering M= values. You may also use the M option to cause recalculation of the adjustment factor at any time (e.g., after editing the file). /P or /PN Controls the use of password protection of mode changes. When you use /P, CLK will ask you for a new password. It will then ask you to repeat the password to ensure that you entered what you want. It does not display the password as you enter it. T h e password is then passed to CLOCK.SYS and password protection is enabled. On future calls to CLOCK.SYS, you will be asked for the password if protection is enabled. You may use /PN to disable password protection, but you will have to provide the current password to do so. If used with the /S feature, the password protection will remain in effect even across reboots. /P should be the last field on a CLK command line. /S or /Sfile Saves the current copy of CLOCK.SYS as it resides in memory. If you do not specify the file, the memory version is written to file CLOCK.NEW in the same directory that contains CLK.EXE. While you may directly overwrite the file CLOCK.SYS, you should be very careful doing so as whatever your current state is will take effect on the next boot. PLEASE MAKE A BACKUP COPY of your original CLOCK.SYS before replacing it with a saved file. The saved file does not do any probing at boot time as it already knows exactly what your clock is. It does not need any parameters on the device= line in CONFIG.SYS. The /S option may be extremely useful for anyone with multiple similar systems to maintain. You can set up all of your options once on one machine, save those with the /S option, and 23 CLOCK Version 3.70 November 20, 1994 then use the saved file to directly install on all the other machines. If you use password protection, no one can change the other systems except by modifying CONFIG.SYS to remove the loading of CLOCK.SYS. You will still need to run CLK as part of every boot operation (e.g., in AUTOEXEC.BAT) to do any automatic adjustment (A= and L= functions), check for clock failures (W= function), and check to see whether the clock should use the standard or day- light offsets (TZ= function). These functions are not processed automatically by CLOCK.SYS because they would in- crease the size of the device driver to an unacceptable limit. /? "/?" or any error will cause CLK to display the usage format. If you have an error in any field, CLK first displays that field. TZ=:? "TZ=:?" or any error in a TZ= function that refers to a pre- defined time zone causes CLK to display all the current pre- defined time zone names and their associated values. 3.2 Using CLK with Windows If you use the TZ= function and also use WINDOWS, you will need to modify your SYSTEM.INI file. The SYSTEM.INI file is found in your WINDOWS directory. WINDOWS performs a function very similar to the C=R function, but WINDOWS uses the BIOS to go directly to the hardware clock and hence bypasses CLOCK.SYS. The result will usually be your time changing everytime you enter WINDOWS. Fortunately you can avoid that by editing the SYSTEM.INI file. In the SYSTEM.INI file, find the line that looks like: [386Enh] Immediately after that line or anywhere in the [386Enh] section, insert a line that looks like: SyncTime=false 3.3 Calculating the Adjustment Factor The M= function will help you determine the value of A=. The most powerful form is M=LAST. Whenever you set the time or date, CLOCK.SYS saves the time that is currently stored in the calendar clock and the new time. Then when you use M=LAST, CLK reads those two values and calculates what the M= function should look like for you. This is especially powerful in that you can use any clock setting program including those that dial the Naval observatory, NIST, or other source. Then immediately follow that operation with CLK M=LAST. Of course, M=LAST is equally valuable if you are adjusting the clock using your watch and the TIME command of DOS. Just follow up with CLK M=LAST and the information will be captured. 24 CLOCK Version 3.70 November 20, 1994 The PC clocks can never be arbitrarily accurate and the best you can do is usually about 5 seconds per month of accuracy. Some PCs will be less accurate at best and others will be more accurate. The drift rate in the clock is not quite a constant and the adjustment factor really only operates to the nearest 18th of a second. For this reason, you are better off waiting to set a new time and use the M= function until your clock is at least a few seconds off. The more accurate your current adjustment, the longer you will wait between manual changes. Of course, that's exactly what automatic adjustment is about anyway. Waiting until an adjustment of several seconds is required keeps the calculation from oscillating due to the inherent errors in the calculation being of the same order of magnitude as the adjustment change. Once you are satisfied that the new adjustment calculated by your M= functions is correct, the easiest way to apply it is to use A=M on a CLK command. A=M tells CLK to use the current calculated adjustment using your previous adjustment and all the M= values as the new adjustment value. It has the same effect as if you had typed A=xxxx where xxxx was the calculated adjustment displayed previously. Example Set time (Use your watch or favorite program) CLK M=LAST Wait a few days or weeks Set time CLK M=LAST Wait a few days or weeks Set time CLK M=LAST Wait a few days or weeks Set time CLK M=LAST (keep repeating until the calculation stabilizes) CLK A=M 3.4 Format of TZ= Function The format of TZ=... can get quite complicated as the standard is trying to deal with all time zones and daylight savings time rules around the world. The full format is: TZ=:zone or TZ=STD[offset][DAY[offset][,start[/time],end[/time]]] Parameters zone The form TZ=:zone is the one you are most likely to need. CLK knows the offsets and daylight savings time rules for most of the U.S. and all you have to supply is the name of your time zone. The time zones currently known to CLK are: EST Eastern U.S. with automatic daylight CST Central U.S. with automatic daylight MST Mountain U.S. with automatic daylight PST Pacific U.S. with automatic daylight 25 CLOCK Version 3.70 November 20, 1994 HST Hawaiian with no daylight savings time MET Mediterranean with automatic daylight You can use CLK TZ=:? to display the list of pre-defined zone names and their values. If you would like your favorite time added, please send me the names, offset from UTC, and any daylight savings time rules that are different from the U.S. NOTE: The names can be composed of any characters except digits, plus, minus, and comma. They can be up to 32 characters long. Case is preserved in the names only for later display by CLK. You can call your zone MyZone. Case is not important in matching the zone names. tz=:cst is the equivalent of TZ=:CST. Both will find the definition of CST. You don't have to wait for me to modify CLK in order to use your local rules or just try something out. That's what the long form is for. STD is any time zone name for standard time that you want to use. See the note above for the rules. offset is the difference between your local time and UTC and is expressed as hh[:mm[:ss]] with an optional leading + or -. Offsets for times West of Greenwich are positive and those East are negative. A 24-hour clock is used with times running from 00:00:00 to 23:59:59. Mountain Standard time would be ex- pressed as: TZ=MST+07:00:00 or TZ=MST7 and that's what you would use if you live in Arizona and don't want any daylight savings time adjustments. DAY is the time zone name for daylight savings time. If you don't use daylight savings time in your location, you should not supply this or any of the following fields. The offset for daylight time is in the same form as for standard time. If you don't give this offset, it is assumed to be one hour later than standard time. Thus a more complete specification of the Eastern time zone would be: 26 CLOCK Version 3.70 November 20, 1994 TZ=EST+05:00:00EDT+04:00:00 or TZ=EST5EDT4 or TZ=EST5EDT (since daylight is one hour later by de- fault) start is the day of the year on which daylight savings time starts. There are three formats that you can use to give this day. They are given below. end is the day of the year on which standard time starts again. Note that in the Southern hemisphere it is quite possible for "end" to be earlier in the year than "start" as daylight savings time will include December and January. end is in the same format as start. Note from the syntax above that you must provide end if you provide start. time is the time of day that the change takes place. It is in exactly the same format as offset except that leading + and - signs are not allowed. If you do not specify the time, 02:00:00 is used as the default. The day of the year form for start and end may be any of: Jn where n is a Julian day of the year from 1 to 365. This form does not allow you to refer to February 29. Day 59 is always February 28 and Day 60 is always March 1. This is most useful in locations where a particular calendar date is used every year. n where n is a Julian day of the year from 0 to 365. This form does allow you to refer to February 29. January 1 is day 0, February 28 is day 58, and either February 29 or March 1 is day 59 depending on whether it is a leap year or not. Not the most useful of forms but it does deal with locations that might specify February 29 as the date that time changes. Mm.w.d is used in places like the U.S. that do not specify a date, but rather specify a rule. m is the month (1 to 12). d is the day of the week (0=Sunday, 1=Monday, ... 6=Saturday). w is the week of the month (1 to 5). Week 1 indicates the first time that day d occurs in that month. Week 5 indicates the last time that day d occurs in that month whether it is the 4th or 5th time. Thus the U.S. rule is M4.1.0/02:00:00,M10.5.0/02:00:00 or the first Sunday in April at 2AM until the last Sunday in October at 2AM. 27 CLOCK Version 3.70 November 20, 1994 The long form for Central U.S. time is: TZ=CST+06:00:00CDT+05:00:00,M4.1.0/02:00:00,M10.5.0/02:00:00 or TZ=CST6CDT5,M4.1.0/2,M10.5.0/2 (just leaving out zeros) or TZ=CST6CDT,M4.1.0,M10.5.0 (since 2AM is default) or TZ=CST6CDT (since the U.S. rule is the default) 3.5 Using CLK The most common use of CLK will be to handle your time zone and daylight savings time changes. You need only do the following: 1. Set your clocks to UTC. 2. Include the following line in your AUTOEXEC.BAT file. CLK TZ=:zone (where you use one of the pre-defined zones) or CLK TZ=... (where you define your own rules) That's it. Everything else will take care of itself. The only other time you will need to do anything is if you decide to correct your calendar clock to a more accurate time. You will probably use TIMESET or one of the other programs that call the Naval Observatory or NIST or maybe just your watch that you have set accurately. If you don't want to have to change the configuration of the time setting program, you may want to have it always set UTC or at least your local standard time. If you want to have it set UTC time, do the following: CLK S=C C=W run your time set program CLK M=LAST (to calculate the adjustment change needed) CLK TZ=... (your normal TZ value) The C=W in the first line is only required if you normally run with the clocks disconnected. Note that if you tell the time set program what your current time zone is, you don't need the S=C or TZ= unless you have the clocks disconnected. Notes Leaving your clock on local time If you don't want to be bothered with UTC, CLK will quite happily work with your calendar clock set to its current value. For example, let's assume that you currently have both clocks set to Pacific Standard Time and you don't really want to be bothered changing to UTC, but you would like future changes between standard and daylight time to be handled automatically. Just use the following statement in AUTOEXEC.BAT: CLK TZ=PST0PDT 28 CLOCK Version 3.70 November 20, 1994 CLK believes whatever you tell it and will quite happily operate assuming that PST is equal to UTC. You could even use CLK with your calendar clock set to Pacific Daylight Time by using: CLK TZ=PST1PDT Avoiding missed days when your PC stays on all night, and missed years and leap days on type 4 and 6 clocks If your PC is often left on over midnight and seems to miss the change to a new day, use: CLK C=R TZ=... in your AUTOEXEC.BAT file to have CLOCK.SYS periodically read the time and date from the calendar clock. If your clock is a type 4 or 6 clock that doesn't update years automatically and doesn't handle leap days, then this setting also ensures that leaving your PC on over the end of a year or across February 29 doesn't cause you to get the wrong date. Using CLK.INI to simplify your commands If you always use the same functions, you may want to edit the CLK.INI file that is included in this release. You can include your TZ=, C=, and R= functions in the file and just use: CLK /I in your AUTOEXEC.BAT file. Adding and subtracting time You can pretty much do anything including simple arithmetic on your clocks by using the functions in the correct sequence. Let's say that you want to add 12 hours to the current time in both clocks because you inadvertently set AM time instead of PM time. The following function sequence will do that: CLK TZ=Igoofed-12 S=D TZ=:pst The TZ=Igoofed-12 (or use any other name for the zone) sets your DOS clock to 12 hours later than the calendar clock. (Yes, I know that time zone offsets seem backwards since you subtract them from the base time, but that's the way the official standards have them.) The S=D sets both clocks to the value in the DOS clock with a zero offset. The TZ=:pst should be replaced by whatever your normal TZ function is or even by a /I to pull in your normal settings. If you normally have your clocks disconnected, insert a C=W function as the first function. Correcting inadvertent problems Just remember that except for the S=D function, CLK and CLOCK.SYS always start with the assumption that the calendar clock is the base and do all their calculations from that point. Thus you can play with TZ and other functions as much as you want and always get back to your normal local time just by using your normal TZ command. The calendar clock will not have been affected unless you did something to set the time or date. You can avoid even that problem by disconnecting your clocks (C=D) or restricting time changes (R=A). 29 CLOCK Version 3.70 November 20, 1994 In fact, if you have trouble with some program messing up your clocks, try the following: CLK C=D execute program CLK S=C C=W (or C=R) TZ=... (your normal) If you have your standard C= and TZ= functions in a file, you can simplify this as: CLK C=D execute program CLK S=C /I You may even want to make up batch files containing this sequence to run those troublesome programs. Some games are major causes of problems because they set the DOS clock running faster or slower than normal to control the pace of the game. As long as they restore the normal rate when they exit, the above sequence will eliminate any clock drift problems. Fast DOS clock drift Some high-speed communication programs will also cause the DOS clock to run slow by causing the BIOS to miss clock interrupts. Fortunately, a C=R function should virtually eliminate problems of this type. 3.6 Examples clk A=0.34 sets an adjustment factor of 0.34 seconds per day. The A=0.34 function will be written to the CLK.INI file along with an L= function with the current time and a zero remaining adjustment. Every time thereafter, that CLK is run with the /I option, it will check to see if it is time to adjust the clocks. About every third day, it will add 1 second to both clocks. clk s=c /i sets the DOS clock to the current calendar clock time without any time zone adjustment. The /i causes all functions in the CLK.INI file to be added. If one of them is a tz function, we have correct- ed the DOS clock for any changes made to it and re-established our time zone. This is a good command line to use following a clk c=d and other operations that may have led to an incorrect time in the DOS clock. clk c=r tz=:est r=b-00:00:02 r=f+00:00:02 sets CLOCK.SYS to read the calendar clock about every 10 seconds and re-synchronize the DOS clock with it; applies the appropriate Eastern time zone (standard or daylight depending on date); and prohibits changes to the clock of more than 2 seconds in either direction. 30 CLOCK Version 3.70 November 20, 1994 3.7 Errors When errors are detected, CLK prints a message. It also sets the ERRORLEVEL on each program termination as follows: 0 Normal termination or only warning messages. 1 Time outside warning range. Warning issued. 2 Error in command line or CLK.INI file functions. The function with the error is displayed followed by the appropriate usage rules. 3 Internal error or system error (e.g., unable to open handle to CLOCK.SYS). 3.8 Future Enhancements Several enhancements are planned for future releases of CLK. - Full screen interface that displays the current status of all the things that CLK and CLOCK.SYS know and lets you change them just by editing the screen. The rather clunky command line interface needs to remain as its compact function definitions are what you want in a .BAT file. 31 CLOCK Version 3.70 November 20, 1994 4. CLKDEMO.EXE A simple version of the CLK program, called CLKDEMO, is provided in both executable and source code form. CLKDEMO only provides support for the C= functions and displaying the clock status. It is included to show you how to add clock handling to your own applications. CLKDEMO is written in C and is compiled with Microsoft Visual C++ but can be compiled with earlier versions like version 5.1. 4.1 CLKDEMO Command Line Syntax CLKDEMO [C=A|D|R|W] [/?] The functions provided work exactly as they do in CLK. CLKDEMO also displays the status and the current times. Since CLKDEMO.EXE is merely a subset of CLK.EXE, it isn't terribly useful as a utility in its own right. Its value is that the source code is provided. There are three source code files provided. CLKDEMO.C is the main program and performs command interpretation and execution. IOCTL.C is a set of functions that read and write the CLOCK$ device driver using the DOS IOCTL functions. IOCTL.H is a set of definitions which are used by CLKDEMO and IOCTL.C. CLKTYP.H is a list of the clock types currently supported by these programs. It is used to display the type. 32 CLOCK Version 3.70 November 20, 1994 5. IOCTL - API TO CLOCK.SYS IOCTL is provided to allow you to build your own applications to use the additional functions that CLOCK.SYS provides. There are several APIs (Application Programming Interfaces) provided as part of IOCTL. These APIs are sufficient to perform all of the extended functions. All of the APIs are defined to be directly callable from all Microsoft compatible languages including MASM, FORTRAN, Pascal, and BASIC. Languages other than C refer to the API names as upper case characters. Object code versions are provided for the small, medium, and large memory models. These may be linked directly with your applications. The object code versions are SIOCTL.OBJ, MIOCTL.OBJ, and LIOCTL.OBJ for the small, medium, and large models respectively. 5.1 Data Structures Data structures are defined in ioctl.h that are used in the calls to the IOCTL functions. /* "modes" holds flags that control the operation of CLOCK.SYS */ struct modes { unsigned : 9; unsigned day_light: 1; unsigned disp_24 : 1; unsigned disp_tim : 1; unsigned pw_ena : 1; unsigned disabl : 1; unsigned chk_forw : 1; unsigned chk_back : 1; }; /* "off" holds a time offset in hours, minutes, and seconds. */ struct off { int hour; int minute; int second; }; /* "date_time" is a structure that holds a date and time. */ struct date_time { int year; int month; int day; struct off time; int hsecond; }; 33 CLOCK Version 3.70 November 20, 1994 /* "time_zone" holds a time zone name and offset. */ struct time_zone { struct off offs; unsigned char zone[32]; }; /* "limit" is used to hold the data that sets time limits for changes. */ struct limit { struct off back; struct off forward; }; /* "disp" is used to hold the data that specifies the location and attributes of the continuous time display. */ struct disp { int x; int y; int attribute; }; /* CLOCK_DATA is the CLOCK.SYS data that is returned by clksta (AKA CLKSTA for FORTRAN, Pascal, and BASIC languages). Because we need to be language independent, all of the data is word-aligned. Only the data types int and character are used. Some of the int data is encoded bits or addresses. */ struct CLOCK_DATA { int connected; /* Connection state */ struct modes mode; /* Mode bits */ struct date_time cal_time; /* Current date and time */ struct time_zone standard; /* Offset of standard UTC */ struct time_zone daylight; /* Daylight offset */ struct limit rules; /* Maximum clock movement */ struct disp display; /* Time display loc and attr */ unsigned char vers[6]; /* CLOCK.SYS version nnn.nn */ int clock_type; /* Type of clock installed */ int ct_1; /* Data for clock type */ int ct_2; int ct_3; int ct_4; unsigned int clock_seg; /* Segment CLOCK.SYS loaded at*/ unsigned int clock_long; /* Size of CLOCK.SYS */ struct date_time prev_time; /* Time just before change */ struct date_time new_time; /* Time just set */ }; This data structure is treated as the following integer array in the FORTRAN and BASIC languages. BASIC OPTION BASE 1 DIM CDATA(80) 34 CLOCK Version 3.70 November 20, 1994 FORTRAN INTEGER*2 CDATA(80) ARRAY INDEX CONTENTS STRUCTURE ELEMENT CDATA(1) = Connection state connected CDATA(2) = Mode bits mode CDATA(3) = Year from calendar clock cal_time.year CDATA(4) = Month cal_time.month CDATA(5) = Day cal_time.day CDATA(6) = Hour cal_time.offs.hour CDATA(7) = Minute cal_time.offs.minute CDATA(8) = Second cal_time.offs.second CDATA(9) = 100th of second cal_time.hsecond CDATA(10) = Standard hours from UTC standard.offs.hour CDATA(11) = Standard minutes standard.offs.minute CDATA(12) = Standard seconds standard.offs.second CDATA(13) - standard.zone CDATA(28) = Standard time zone LJSF CDATA(29) = Daylight hours from UTC daylight.offs.hour CDATA(30) = Daylight minutes daylight.offs.minute CDATA(31) = Daylight seconds daylight.offs.second CDATA(32) - daylight.zone CDATA(47) = Daylight time zone LJSF CDATA(48) = Maximum hours backward rules.back.hour CDATA(49) = Maximum minutes backward rules.back.minute CDATA(50) = Maximum seconds backward rules.back.second CDATA(51) = Maximum hours forward rules.forward.hour CDATA(52) = Maximum minutes forward rules.forward.minute CDATA(53) = Maximum seconds forward rules.forward.second CDATA(54) = x cursor position display.x CDATA(55) = y cursor position display.y CDATA(56) = attribute display.attribute CDATA(57) - vers CDATA(59) = CLOCK.SYS version LJSF CDATA(60) = Clock type clock_type CDATA(61) = I/O address, base memory ct_1 segment, or base year CDATA(62) = Read memory offset ct_2 CDATA(63) = Write-0 memory offset ct_3 CDATA(64) = Write-1 memory offset ct_4 CDATA(65) = Segment address clock_seg where CLOCK.SYS is loaded CDATA(66) = Length of CLOCK.SYS clock_long CDATA(67) = Year from previous prev_time.year CDATA(68) = Month prev_time.month CDATA(69) = Day prev_time.day CDATA(70) = Hour prev_time.offs.hour CDATA(71) = Minute prev_time.offs.minute CDATA(72) = Second prev_time.offs.second CDATA(73) = 100th of second prev_time.hsecond CDATA(74) = Year from new time new_time.year CDATA(75) = Month new_time.month CDATA(76) = Day new_time.day CDATA(77) = Hour new_time.offs.hour 35 CLOCK Version 3.70 November 20, 1994 CDATA(78) = Minute new_time.offs.minute CDATA(79) = Second new_time.offs.second CDATA(80) = 100th of second new_time.hsecond 5.2 clksta ■ Summary C #include <ioctl.h> extern int pascal far clksta(struct CLOCK_DATA *cdata); BASIC OPTION BASE 1 DIM CDATA(80) DECLARE FUNCTION CLKSTA%(BYVAL Addr AS INTEGER) STATUS% = CLKSTA(VARPTR(CDATA(1))) FORTRAN INTEGER*2 CDATA(80) INTEGER*2 STATUS INTEGER*2 CLKSTA STATUS = CLKSTA(CDATA) ■ Description clksta returns all of the information about CLOCK.SYS in a structure. In FORTRAN and BASIC the structure appears to be an integer array. The above structure declarations can be approximated in Pascal. For a description of the values of each element, see the individual APIs below. The elements not described as part of the input to other functions are: unsigned char vers[6]; /* CLOCK.SYS version nnn.nn */ int clock_type; /* Type of clock installed */ int ct_1; /* Data for clock type */ int ct_2; int ct_3; int ct_4; unsigned int clock_seg; /* Segment CLOCK.SYS loaded at */ unsigned int clock_long; /* Size of CLOCK.SYS */ CDATA(57) - CDATA(59) = CLOCK.SYS version LJSF characters CDATA(60) = Clock type (see type numbers in appendix B) CDATA(61) = I/O address, base memory segment, or base year CDATA(62) = Read memory offset CDATA(63) = Write-0 memory offset 36 CLOCK Version 3.70 November 20, 1994 CDATA(64) = Write-1 memory offset CDATA(65) = Segment address at which CLOCK.SYS is loaded CDATA(66) = Length in bytes of CLOCK.SYS vers or CDATA(57) - CDATA(59) Is the version number of the CLOCK.SYS that is installed. This is returned as a 6-character, left-justified, space-filled (LJSF) character string. For example, "3.49 ". clock_type or CDATA(60) Is the type number of the clock being used. See Appendix B for the type numbers. ct_1 or CDATA(61) Is the value of the first clock parameter. This is the base I/O address for I/O bus clocks, the base memory segment address for memory-mapped clocks, or the base year for the AT&T clocks. ct_2 or CDATA(62) Is the read offset for memory-mapped clocks. ct_3 or CDATA(63) Is the write 0-bits offset for memory-mapped clocks. ct_4 or CDATA(64) Is the write 1-bits offset for memory-mapped clocks. clock_seg or CDATA(65) Is the segment address at which CLOCK.SYS is loaded. CLOCK.SYS always starts at offset zero in this segment. clock_long or CDATA(66) Is the length of CLOCK.SYS in bytes. ■ Arguments cdata is a pointer to a location to place the current state information from CLOCK.SYS. ■ Return Value If clksta is successful, the function returns 0. Otherwise, it returns a non- zero value and _doserrno is set to the corresponding error code. Possible values are: 0001h Invalid function. This should indicate that CLOCK.SYS is not installed. It is the error that the DOS clock device driver would return since it doesn't handle these functions. 0005h Access denied. Indicates that DOS would not open a handle for read access. You may not have enough handles available. 0006h Invalid handle. Should not happen. 000Dh Invalid data. CLOCK.SYS reported a bad byte count or otherwise did not process the request. This should not happen. 37 CLOCK Version 3.70 November 20, 1994 5.3 setpw ■ Summary C #include <ioctl.h> extern void pascal far setpw(unsigned char *pw); BASIC DECLARE SUB SETPW(BYVAL S AS INTEGER) A$ = "MyPasswd" CALL SETPW(SADD(A$)) Note that A$ must be at least 8 characters long. Only the first 8 characters will be used. FORTRAN CHARACTER*8 PW PW = "MyPasswd" CALL SETPW(PW) ■ Description The setpw function sets the password to be used on subsequent calls to any of the following functions. These functions automatically supply the most recent password when they call CLOCK.SYS. You need not ever call setpw if you are not using password protection. CLOCK.SYS will only check the password if password protection is enabled through the stmode function. ■ Arguments pw is a pointer to the password string. This string should be exactly 8 characters long and must be at least 8 characters long. The password should also be LJSF as every character is significant. Case is significant in passwords. 38 CLOCK Version 3.70 November 20, 1994 ■ Example #include <ioctl.h> main() { unsigned char pw[9] = "MyPasswd"; /* Set password to use on subsequent function calls. */ setpw(pw); } 5.4 connec ■ Summary C #include <ioctl.h> extern int pascal far connec(int *conn); BASIC DECLARE FUNCTION CONNEC%(CONN AS INTEGER) STATUS% = CONNEC(CONN) FORTRAN INTEGER*2 CONN, STATUS, CONNEC STATUS = CONNEC(CONN) ■ Description The connec function provides a means of setting the connection state of CLOCK.SYS. ■ Arguments conn specifies the new connection mode. The values are: 0 = disconnected (C=D) 1 = connected for writes only (C=W) 2 = connected for writes and periodic reads (C=R) 3 = connected for all operations (C=A) ■ Return Value If the return value is zero, the function succeeded. If the return value is non-zero, an error has occurred and _doserrno is set to the corresponding 39 CLOCK Version 3.70 November 20, 1994 error code. Possible values are: 0001h Invalid function. This should indicate that CLOCK.SYS is not installed. It is the error that the DOS clock device driver would return since it doesn't handle these functions. 0005h Access denied. Indicates that DOS would not open a handle for read access. You may not have enough handles available. 0006h Invalid handle. Should not happen. 000Dh Invalid data. CLOCK.SYS reported a bad byte count or otherwise did not process the request. This should not happen. ■ Example #include <stdio.h> #include <ioctl.h> main() { int conn_write = 1; int status; /* Set clock to connected for writes */ status = connec(&conn_write); if (status) printf("Error %X in connec\n", status); } 5.5 newpw ■ Summary C #include <ioctl.h> extern int pascal far newpw(unsigned char *pw); BASIC DECLARE FUNCTION NEWPW%(BYVAL S AS INTEGER) A$ = "MyPasswd" STATUS% = NEWPW(SADD(A$)) Note that A$ must be at least 8 characters long. Only the first 8 characters will be used. 40 CLOCK Version 3.70 November 20, 1994 FORTRAN CHARACTER*8 PW INTEGER*2 STATUS, NEWPW PW = "MyPasswd" STATUS = NEWPW(PW) ■ Description The newpw function sets a new password for CLOCK.SYS. This function is not sufficient to enable password protection. You must also use stmode to turn on password checking. BE SURE to use newpw before you use stmode to turn on password checking. If you turn on password checking without first setting the password to something that you know, you will never be able to use the CLOCK.SYS functions again until you reboot. ■ Arguments pw is a pointer to the password string. This string should be exactly 8 characters long and must be at least 8 characters long. The password should also be LJSF as every character is significant. Case is significant in passwords. ■ Return Value If the return value is zero, the function succeeded. If the return value is non-zero, an error has occurred and _doserrno is set to the corresponding error code. Possible values are: 0001h Invalid function. This should indicate that CLOCK.SYS is not installed. It is the error that the DOS clock device driver would return since it doesn't handle these functions. 0005h Access denied. Indicates that DOS would not open a handle for read access. You may not have enough handles available. 0006h Invalid handle. Should not happen. 000Dh Invalid data. CLOCK.SYS reported a bad byte count or otherwise did not process the request. This should not happen. 41 CLOCK Version 3.70 November 20, 1994 ■ Example #include <stdio.h> #include <ioctl.h> main() { unsigned char pw[9] = "MyPasswd"; int status; /* Set new password for CLOCK.SYS */ status = setpw(pw); if (status) printf("Error %X in setpw\n", status); } 5.6 rstrct ■ Summary C #include <ioctl.h> extern int pascal far rstrct(int *bhour, int *bmin, int *bsec, int *fhour, int *fmin, int *fsec); BASIC DECLARE FUNCTION RSTRCT%(BHOUR%, BMIN%, BSEC%, FHOUR%, FMIN%, FSEC%) FORTRAN INTEGER*2 BHOUR, BMIN, BSEC, FHOUR, FMIN, FSEC INTEGER*2 RSTRCT STATUS = RSTRCT(BHOUR, BMIN, BSEC, FHOUR, FMIN, FSEC) ■ Description The rstrct function sets backwards and forwards limits on time changes. Any time changes that exceed these limits will be ignored. For example, if a backward limit of 2 seconds is set, no change that would move the clock backwards more than 2 seconds will be processed. Setting the limits protects you agains keying in a bad time and agains programs that may incorrectly set the time. Yet you can still change the time within the prescribed limits. For example, you may set a backward limit of 2 seconds to permit CLK to adjust the time by up to 2 seconds while inhibiting any other backwards changes. These limits have no effect on changing between standard and daylight times as that is not really a change in the "time". 42 CLOCK Version 3.70 November 20, 1994 ■ Arguments bhour:bmin:bsec is the backward limit in hours, minutes and seconds. fhour:fmin:fsec is the forward limit in hours, minutes, and seconds. ■ Return Value If the return value is zero, the function succeeded. If the return value is non-zero, an error has occurred and _doserrno is set to the corresponding error code. Possible values are: 0001h Invalid function. This should indicate that CLOCK.SYS is not installed. It is the error that the DOS clock device driver would return since it doesn't handle these functions. 0005h Access denied. Indicates that DOS would not open a handle for read access. You may not have enough handles available. 0006h Invalid handle. Should not happen. 000Dh Invalid data. CLOCK.SYS reported a bad byte count or otherwise did not process the request. This should not happen. ■ Example #include <stdio.h> #include <ioctl.h> main() { int bhour = 0; int bmin = 0; int bsec = 2; int fhour = 1; int fmin = 0; int fsec = 0; int status; /* Set time change limits to 2 seconds backwards and 1 hour forwards */ status = rstrct(&bhour, &bmin, &bsec, &fhour, &fmin, &fsec); if (status) printf("Error %X in rstrct\n", status); else printf("Time limits set to " "-%.2d:%.2d:%.2d,+%.2d:%.2d:%.2d\n", bhour, bmin, bsec, fhour, fmin, fsec); } 43 CLOCK Version 3.70 November 20, 1994 5.7 stmode ■ Summary C #include <ioctl.h> extern int pascal far stmode(struct modes *mode); BASIC DECLARE FUNCTION STMODE%(MODES%) FORTRAN INTEGER*2 MODES INTEGER*2 STMODE STATUS = STMODE(MODES) ■ Description The stmode function sets a variety of operating modes. The argument is actually a structure of bits. Each bit specifies whether an operating mode is on (1) or off (0). ■ Arguments modes is set of bits that specify operating modes. The bit values are: unsigned : 9; Unused unsigned day_light: 1; 0x0200 (512) unsigned disp_24 : 1; 0x0400 (1024) unsigned disp_tim : 1; 0x0800 (2048) unsigned pw_ena : 1; 0x1000 (4096) unsigned disabl : 1; 0x2000 (8192) unsigned chk_forw : 1; 0x4000 (16384) unsigned chk_back : 1; 0x8000 (32768) ■ Return Value If the return value is zero, the function succeeded. If the return value is non-zero, an error has occurred and _doserrno is set to the corresponding error code. Possible values are: 0001h Invalid function. This should indicate that CLOCK.SYS is not installed. It is the error that the DOS clock device driver would return since it doesn't handle these functions. 0005h Access denied. Indicates that DOS would not open a handle for read access. You may not have enough handles available. 0006h Invalid handle. Should not happen. 44 CLOCK Version 3.70 November 20, 1994 000Dh Invalid data. CLOCK.SYS reported a bad byte count or otherwise did not process the request. This should not happen. ■ Example #include <ioctl.h> main() { struct CLOCK_DATA cdata; /* Set daylight savings time. */ clksta(&cdata); /* Get current mode settings. */ cdata.mode.day_light = 1; /* Turn on daylight */ stmode(&cdata.modes); } 5.8 stzone ■ Summary C #include <ioctl.h> extern int pascal far stzone(int *shour, int *smin, int *ssec, unsigned char sname[32], int *dhour, int *dmin, int *dsec, unsigned char dname[32]); BASIC DECLARE FUNCTION STZONE%(SHOUR%, SMIN%, SSEC%, BYVAL SN AS INTEGER, DHOUR%, DMIN%, DSEC%, BYVAL DN AS INTEGER) SNAME$ = "32-CHARACTER STANDARD ZONE NAME " DNAME$ = "Daylight savings time zone name " STATUS% = STZONE(6,0,0,SADD(SNAME$),5,0,0,SADD(DNAME$)) FORTRAN CHARACTER*32 SNAME, DNAME INTEGER*2 STZONE, STATUS SNAME = "CST" DNAME = "CDT" STATUS = STZONE(6, 0, 0, SNAME, 5, 0, 0, DNAME) 45 CLOCK Version 3.70 November 20, 1994 ■ Description The stzone function sets the standard time and daylight savings time offsets from the calendar clock and the standard and daylight time zone names or mnemonics. Note that the offsets are subtracted from the calendar clock to get the local time. Thus the standard time offset from UTC to EST is 5:0:0. ■ Arguments SHOUR:SMIN:SSEC is the time difference between the calendar clock and local standard time. It may be a positive of negative value. If negative, all three values must be negative. SNAME is the standard time zone name or mnemonic. It must be a 32-character LJSF character string. As with all other character strings used by these functions, there is no terminating NULL character as is usual in C. The other languages do not readily handle NULL terminated strings. In C applications you may define the character array to contain 33 characters, but you must ensure that the NULL character does not occur in the first 32 characters. DHOUR:DMIN:DSEC is the time difference between the calendar clock and local daylight savings time. Whether the standard offset or the daylight offset is currently used by CLOCK.SYS is controlled by the setting of the day_light mode bit (see stmode). DNAME is the daylight savings time zone name or mnemonic. It must be a 32-character LJSF character string. ■ Return Value If the return value is zero, the function succeeded. If the return value is non-zero, an error has occurred and _doserrno is set to the corresponding error code. Possible values are: 0001h Invalid function. This should indicate that CLOCK.SYS is not installed. It is the error that the DOS clock device driver would return since it doesn't handle these functions. 0005h Access denied. Indicates that DOS would not open a handle for read access. You may not have enough handles available. 0006h Invalid handle. Should not happen. 000Dh Invalid data. CLOCK.SYS reported a bad byte count or otherwise did not process the request. This should not happen. 46 CLOCK Version 3.70 November 20, 1994 ■ Example #include <stdio.h> #include <ioctl.h> main() { unsigned char sname[33] = "PST "; unsigned char dname[33] = "PDT "; int shour = 8; int smin = 0; int ssec = 0; int dhour = 7; int dmin = 0; int dsec = 0; struct CLOCK_DATA cdata; /* Get current status. */ clksta(&cdata); /* Set time zone to U.S. Pacific time. */ stzone(&shour, &smin, &ssec, sname, &dhour, &dmin, &dsec, dname); /* Select daylight savings time. */ cdata.mode.day_light = 1; stmode(&cdata.mode); } 5.9 tdisp ■ Summary C #include <ioctl.h> extern int pascal far tdisp(int *dispx, int *dispy, int *attr); BASIC DECLARE FUNCTION TDISP%(DISPX%, DISPY%, ATTR%) STATUS% = TDISP(72, 0, &H79) FORTRAN INTEGER*2 TDISP, STATUS STATUS = TDISP(0, 72, 0x79) 47 CLOCK Version 3.70 November 20, 1994 ■ Description The tdisp function sets the coordinates and attribute for the continuous time display. tdisp does not start or stop the continuous display nor does it set the 12-hour or 24-hour mode. Those are all provided by the stmode function. ■ Arguments DISPX is the x (horizontal) cursor coordinate for the continuous time display. The rightmost character on a line is at x=0. Be sure to leave enough space at the end of the line to accommodate the entire 8-char- aracter time display. For example, x=72 is the last position to specify on an 80-character line. DISPY is the y (vertical) cursor coordinate for the continuous time display. The top line on the display is y=0. ATTR is the display attribute to use for the continuous time display. ATTR is usually expressed as two hex digits. The first (high-order) digit is the back- ground color (0 to 7) and the second digit is the text or foreground color (0 to F). For example, 0A would display bright green letters on a black back- ground. Background colors usually do not include the bright colors. The color numbers are: 0 Black 1 Blue 2 Green 3 Cyan 4 Red 5 Magenta 6 Brown 7 White 8 Grey 9 Bright blue A Bright green B Brigth cyan C Bright red D Bright magenta E Yellow F Bright White ■ Return Value If the return value is zero, the function succeeded. If the return value is non-zero, an error has occurred and _doserrno is set to the corresponding error code. Possible values are: 0001h Invalid function. This should indicate that CLOCK.SYS is not installed. It is the error that the DOS clock device driver would return since it doesn't handle these functions. 48 CLOCK Version 3.70 November 20, 1994 0005h Access denied. Indicates that DOS would not open a handle for read access. You may not have enough handles available. 0006h Invalid handle. Should not happen. 000Dh Invalid data. CLOCK.SYS reported a bad byte count or otherwise did not process the request. This should not happen. ■ Example #include <stdio.h> #include <ioctl.h> main() { struct CLOCK_DATA cdata; int dispx = 72; int dispy = 0; int attr = 0x79; /* Get current CLOCK.SYS modes. */ clksta(&cdata); /* Turn on 12-hour display at end of top line of screen. Use bright blue text on a white backgroun. */ tdisp(&dispx, &dispy, &attr); cdata.mode.disp_tim = 1; cdata.mode.disp_24 = 0; stmode(&cdata.mode); } 49 CLOCK Version 3.70 November 20, 1994 6. CLOCK.SYS - ASSEMBLY LANGUAGE API CLOCK.SYS has a couple of additional APIs (Application Programming Interfaces) that are not present in the normal DOS CLOCK$ device driver. These interfaces are provided by the DOS IOCTL (Input/Output of ConTroL data) functions. The Output Control Data to Character Device function is used to set new operating values for CLOCK.SYS for the C=, D=, R=, TZ=, and /P functions. The Input Control Data from Character Device function is used to get the current status and the date and time from the calendar clock. 6.1 Opening the CLOCK$ Device In order to use the additional APIs provided by CLOCK.SYS you must open a handle to the CLOCK$ device driver. You do this using the DOS INT 21H Open File with Handle (3DH) function specifying read-write access. You then use the handle to invoke the other functions. Sample assembly language is: MOV AX,3D00H ; Open with read and write access MOV DX,OFFSET filename ; Pointer to "CLOCK$" ASCIIZ string ; DS:DX must point to the string INT 21H ; Call DOS function handler ; AX contains the handle on return if carry flag is not set. 6.2 Sending New Values to CLOCK.SYS To change the state of CLOCK.SYS, you use the Send Control Data to Character Device (4403H) DOS function. You send data to specify the connection type, m o des, time zone offsets and names, restrictions, continuous display information, and password. You may send any combination of these in any order. You must always send the current password as the first 8 bytes. If password checking is not enabled, it doesn't matter what the 8 bytes contain, but you must still send the 8 bytes. The data stream that you send to CLOCK.SYS consists of the current password followed by a selection index, the data for that selection, another selection index, its data, and so on. The selection indices and the data stream associated with each one are: INDEX DATA ITEMS COMMENTS 1 connected two byte integer (0 : C=D, 1 : C=W, 2 : C=R, 3 : C=A) 2 mode two byte integer (see stmode for a description of the bits) 3 standard time_zone structure for standard time daylight time_zone structure for daylight time 4 rules limits structure 5 display disp structure 6 password 8 bytes LJSF of new password 50 CLOCK Version 3.70 November 20, 1994 Sample assembly language to send new information to CLOCK.SYS: curpw DB 8 dup(?) ; Current password DW 1 ; Change connection DW 2 ; to C=R DW 4 ; Change limits DW 0,0,2,1,0,0 ; to R=B-::2,F+1 DW 6 ; Set new password DB "MyPasswd" ; to MyPasswd (case is important) DW 2 ; Change modes DW 0D000H ; to enable limits and password ; also sets standard time and ; no display count equ $-curpw ; Length to send ... MOV AX,4403H ; Send control data function MOV BX,handle ; Value returned from open MOV CX,count ; Value = number of bytes to send MOV DX,OFFSET curpw ; Location of bytes to be sent ; DS:DX must point to the buffer INT 21H ; ; OK if carry not set. CX will equal bytes actually taken. 6.3 Getting Current Status of CLOCK.SYS To get the current status and time, you use the Receive Control Data from Character Device (4402H) function. You can read all of the CLOCK_DATA structure or any smaller amount of it that you need, but you can only read starting at the beginning Sample assembly language for reading the clock status is: MOV AX,440CH ; Read control data function MOV BX,handle ; Value returned from open MOV CX,count ; Number of bytes to read MOV DX,OFFSET buffer ; Location to store the data ; DS:DX must point to the buffer INT 21H ; Call DOS ; Data returned if carry not set. ; CX will contain the actual number of bytes transferred. 51 CLOCK Version 3.70 November 20, 1994 APPENDIX A: DEFINITION OF SHAREWARE Shareware distribution gives users a chance to try software before buying it. If you try a Shareware program and continue using it, you are expected to register. Individual programs differ on details -- some request registration while others require it, some specify a maximum trial period. With registra- tion, you get anything from the simple right to continue using the software to an updated program with printed manual. Copyright laws apply to both Shareware and commercial software, and the copyright holder retains all rights, with a few specific exceptions as stated below. Shareware authors are accomplished programmers, just like commercial authors, and the programs are of comparable quality. (In both cases, there are good programs and bad ones!) The main difference is in the method of distribu- tion. The author specifically grants the right to copy and distribute the software, either to all and sundry or to a specific group. For example, some authors require written permission before a commercial disk vendor may copy their Shareware. Shareware is a distribution method, not a type of software. You should find software that suits your needs and pocketbook, whether it's commercial or Shareware. The Shareware system makes fitting your needs easier, because you can try before you buy. And because the overhead is low, prices are low also. Shareware has the ultimate money-back guarantee -- if you don't use the product, you don't pay for it. DISCLAIMER - AGREEMENT Users of CLOCK must accept this disclaimer of warranty: "CLOCK is supplied as is. The author disclaims all warranties, expressed or implied, including, without limitation, the warranties of merchantability and of fitness for any purpose. The author assumes no liability for damages, direct or consequen- tial, which may result from the use of CLOCK." CLOCK is a "shareware program" and is provided at no charge to the user for evaluation. Feel free to share it with your friends, but please do not give it away altered or as part of another system. The essence of "user-supported" software is to provide personal computer users with quality software without high prices, and yet to provide incentive for programmers to continue to develop new products. If you find this program useful and find that you are using CLOCK and continue to use CLOCK after a reasonable trial period, you must make a registration payment of $10 to Ronald Q. Smith. The $10 regis- tration fee will license one copy for use on any one computer at any one time. For a registration fee of $25, I will immediately send you the latest version of CLOCK including the source code and this document as a WordPerfect 5.1 file. You may use the source code for your own maintenance of CLOCK or as a learning tool for any software that you develop. You may not use all or part of the source code in any software that you develop or release to others without the permission of Ronald Q. Smith. You must treat this software just like a book. An example is that this software may be used by any number of people and may be freely moved from one computer location to another, so long as there is no possibility of it being used at one location while it's being used at another. Just as a book cannot be read by two different persons at the same time. 52 CLOCK Version 3.70 November 20, 1994 Commercial users of CLOCK must register and pay for their copies of CLOCK within 30 days of first use or their license is withdrawn. Site-License arrangements may be made by contacting Ronald Q. Smith. Anyone distributing CLOCK for any kind of remuneration must first contact Ronald Q. Smith at the address below for authorization. You are encouraged to pass a copy of CLOCK along to your friends for evaluation. Please encourage them to register their copy if they find that they can use it. All registered users will receive a copy of the latest version of the CLOCK system. Send the fees and any inquiries to: Ronald Q. Smith 11 Black Oak Road St. Paul, MN 55127-6204 You may also contact me via CompuServe mail at userid 71620,514. I will be happy to respond to any problems and suggestions for future capabilities. You may register CLOCK through the CompuServe Shareware Registration program. CLOCK.SYS is found under registration ID 104. The fee for registering through CompuServe is $12 (to cover their charge) and will be added directly to your CompuServe bill. 53 CLOCK Version 3.70 November 20, 1994 APPENDIX B: CLOCK TYPES B.1 Type 0 - PC/AT IBM PC/AT and all fully compatible PCs. Most versions of DOS fully support this clock interface without a separate driver. Use CLOCK.SYS to provide sup- port for CLK.EXE and CLKDEMO.EXE. If you don't need the extra functions of CLK, you probably don't need CLOCK.SYS. However, there were a couple of late 8088 PCs that adopted the PC/AT clock standard but did not provide the PC/AT recognition sentinel. DOS will not find the clock, but CLOCK.SYS will. Amstrad PC1521DD and NEC MultiSpeed systems use this type of clock. Automatic determination checks location F000:FFFE for the hex value FC. Also checks by just trying to read the time and seeing if we get the correct answer. BIOS calls are used to read and write the clock values which are usually stored in the CMOS RAM along with other configuration information. The primary interfaces are: Get Date: MOV AH,4 INT 1AH Returns the year in CX and month and day in DX in BCD format (e.g., a hex display would show: CX=1991, DX=1009 for October 9, 1991). Set Date: MOV AH,5 Load CX and DX as above for Get Date INT 1AH Get Time: MOV AH,2 INT 1AH Returns hours and minutes in CX and seconds in DH in BCD format. May also return 100ths of seconds in DL (e.g., CX=2359, DX=5900 for 1 second before midnight). Set Time: MOV AH,3 Load CX and DX as for Get Time INT 1AH B.2 Type 1 - Zenith Z-18x portables, Supersport 20 Automatic determination checks location F000:FFFA for the two-byte hex value 4D32 ("M2"). BIOS calls are used to read and write the clock. 54 CLOCK Version 3.70 November 20, 1994 Get Date: MOV AH,2 INT 1AH Returns CX=year (1980 - 2079) in binary and DH=month, DL=day. All values are binary. A hex display of the above date would look like CX=7C7, DX=A09. Set Date: MOV AH,3 Load CX and DX as for Get Date. INT 1AH Get Time: MOV AH,4 INT 1AH Returns CH=hours, CL=minutes, DH=seconds. A hex display would show: CX=173B, DX=3B00. Set Time: MOV AH,5 Load CX and DX as for Get Time. INT 1AH B.3 Type 2 - Various Zenith Data System PCs. A u t omatic determination looks at location F000:800A for the pattern 00,F0,"ZDS". Get Date: MOV AH,2AH INT 1AH Returns CX and DX as for type 1. Set Date: MOV AH,2BH Load CX and DX as for type 1. INT 1AH Get Time: MOV AH,2CH INT 1AH Returns CX and DX as for type 1. Set Time: MOV AH,2DH Load CX and DX as for type 1. INT 1AH B.4 Type 3 - Memory-Mapped Clocks Memory-mapped clock used on some Zenith Data Systems PCs and other similar clocks including many slot-less or no-slot clocks. The SMT (Systems Manufacturing Technology) No-Slot clocks are supported by this type. Automatic determination is to attempt to read the clock. If values other than all 0FFH or 0 are obtained, this clock type is chosen. All known segments and offsets are tried. Several different memory mapping approaches are used and many different address possibilities are supported. In general a segment address in the ROM region (C800H through FFFFH) is used. Offsets from that segment address are 55 CLOCK Version 3.70 November 20, 1994 used to read bits, write zero bits, and write one bits. Documentation may specify those segments and addresses in several forms. For example, segment F000 with offset F002 is the same as segment FF00 with offset 2. Each memory reference reads or writes a single bit. Read operations are used for all references with separate offsets for reading a bit, writing a zero bit, and writing a one bit. Clock segments and addresses currently probed include: ╔═══════╤═════════╤════════╤═════╤═════╤═════╤════════╗ ║SEGMENT│WRITE 0 │WRITE 1 │READ │DECR │LAST │VENDOR ║ ╟───────┼─────────┼────────┼─────┼─────┼─────┼────────╢ ║F000 │ F002 │F003 │F004 │0000 │F000 │(Zenith)║ ╟───────┼─────────┼────────┼─────┼─────┼─────┼────────╢ ║FE00 │ 2 │ 3 │ 5 │0080 │C800 │SMT ║ ╟───────┼─────────┼────────┼─────┼─────┼─────┼────────╢ ║FE00 │ 0 │ 2 │ 8 │0080 │C800 │SMT ║ ╚═══════╧═════════╧════════╧═════╧═════╧═════╧════════╝ Multiple address combinations may be tried for each clock pattern. The DECR value is subtracted from the SEGMENT value for another attempt at probing until the value equals LAST. Note that like the SEGMENT address, DECR and LAST are in units of paragraphs (16-bytes). Thus DECR of 80 is equivalent to 800H or 2048 bytes. When the addresses used by a memory-mapped clock are determined by probing, the segment and read address is displayed. As the read address varies the most from one clock manufacturer to another it is a good indication of the type of clock found. Data is stored in BCD in bytes that you construct by shifting in the bits. The most important data bytes are: 0 = Hundredths of seconds 1 = Seconds 2 = Minutes 3 = hours 5 = days 6 = months 7 = years mod 1980 B.5 Type 4 - Direct Register I/O Bus Clock Many add-in clocks on expansion boards use this type of clock. Some built-in clocks in PCs are also accessed similarly. This clock was used on many AST Research I/O boards for 8088 PCs such as the Six-Pack Plus, IO Plus, etc. Also used on some Tandy systems (e.g., 1200HD) and the Vendex Turbo-888-XT. Automatic determination is to attempt to read, complement, write, re-read, and re-complement one of the registers. If the first value read and the re-complemented second value are equal, the register exists and is presumed to be the clock. See also the description for types 6 and 7. If you aren't sure which variant 56 CLOCK Version 3.70 November 20, 1994 you have, specify type 8 and automatic probing will determine if it is really a type 4, 6, or 7. For the greatest chance of detecting the correct clock type, supply the base I/O address if at all possible. NOTE: If the clock is not correctly initialized (e.g., you have just replaced the battery), CLOCK.SYS must initialize it so that the counters will start working. CLOCK.SYS determines that the clock has been previously initialized by looking at register 14H (see B below). If register B contains the value 0DEH, the clock is presumed to be initialized. If not, CLOCK.SYS will clear all the registers to zero and start the counters running. While this form of checking for initialization was commonly used, your previous software may have used a different method. If so, the first time you run CLOCK.SYS your date and time may be set to zero (1980-1-1 00:00:00). If that happens, just enter the date and time. It should work OK after that without resetting to zero on further boots. Each clock register is implemented as a separate I/O register address. Clock base I/O addresses of 240H, 2C0H, 300H, and 340H are supported by automatic probing. Similar clocks at other base I/O addresses are supported by specifying type 4 and the base address. The address range used is the base plus 0 through 1FH (e.g., 2C0H through 2DFH). Important registers are (using 2C0 as the example): 2C1 = 100ths of seconds 2C2 = seconds 2C3 = minutes 2C4 = hours 2C6 = days 2C7 = months 2C9 = month last time clock was read/set 2CA = years 2CB = initialized flag (0DEH if initialized) 2D4 = Status All values are in BCD. That means that each register consists of two 4-bit nybbles (a nybble is to a nibble as a byte is to a bite - I haven't seen this used recently, but as a bit of trivia, the first IBM 360 principles of operation manuals used that term and that spelling - at least in a draft copy that we got in 1965). Each nybble contains one decimal digit of the value. Years are mod 1980 (i.e., 0 means 1980, 99 means 2079). Since these clocks do not keep the year and do not handle leap years for you, CLOCK.SYS does the necessary calculations to keep the year correctly main- tained and to adjust the date for leap days. The clocks do provide a couple of memory locations in which CLOCK.SYS maintains the year and previous month. As long as you boot your system before a full year has passed, CLOCK.SYS will correctly maintain the date. 57 CLOCK Version 3.70 November 20, 1994 B.6 Type 5 - Mitsubishi 8088 PCs These were sold by Sperry as the PC-1 and PC/HT, by Leading Edge as the Model D, by Mitsubishi, and others. Automatic determination checks location F000:FFB3 for the string "MITSUBISHI". Later Mitsubishi PCs which used a different clock had the same string at a different location. We hope all early versions had it at this location. BIOS functions are used to access the clock. Get Date: MOV AH,4 INT 1AH Returns CL=year mod 1980, DH=month, and DL=day all in binary. Also sets AL=0FFH if the clock is busy and the request should be retried. Set Date: MOV AH,5 Load CL, DX as for Get Date. INT 1AH Returns AL=0FFH if busy. Get Time: MOV AH,2 INT 1AH Returns CH=hour, CL=minute, DH=second, and AL=status. AL=0FFH means busy. AL=0 means 24-hour mode. AL=1 means AM and AL=3 means PM. Set Time: MOV AH,3 Load AL, CX, DH as for Get Time. INT 1AH Returns AL=0FFH if busy. NOTE: Some early Mitsubishi PCs came with fixed disk controllers that were not DOS compatible. In addition to the clock modifications, the DOS for those systems also handled the disk controller variant. If you have such a PC, CLOCK.SYS is not sufficient to enable you to go above DOS level 3.2. You will also need to replace your fixed disk controller. I strongly suggest that you create a boot floppy for your current DOS level before you try to install your new DOS level. Then boot your new DOS from a floppy disk, do SYS C: and copy COMMAND.COM to C:, then try a disk boot. If the disk boot fails, boot the floppy you just created and do a SYS C: and copy COMMAND.COM to C: to restore your old DOS version. At that point, your best bet is to simply give up and stay with DOS 3.2. If you want to proceed, you must replace your fixed disk controller. If SYS C: gives you an error status that indicates that there isn't room for the new DOS version (very possible when moving from 3.2 to 3.3 or above), you must backup your entire fixed disk and use FORMAT C:/S to place the new version of DOS on the disk. While this is a hassle, at least if your PC won't boot from the disk, the fall-back approach is identical. There will be room to put DOS 3.2 or earlier back on the fixed disk. 58 CLOCK Version 3.70 November 20, 1994 B.7 Type 6 - Indirect Register I/O Bus Clock Used on AST Research boards and others. Typically uses the same I/O base address as type 4. However the clock registers are selected by sending the register address to the base I/O address and then reading or writing data at the base I/O address + 1. The internal register numbers and their contents are the same as for type 4. Automatic determination by probing the address register. If the low-order bit is one, it may be this type of clock or type 7. We then look further to determine if it is type 7. If you aren't sure which type of clock you have but believe it is type 4, 6 or 7, specify type 8 and automatic probing will detect which variant it is. If at all possible specify the base I/O address as that will increase the likelihood that the correct determination is made. I/O addresses used are (again using 2C0 as the example base address): 2C0 = Address register. Writing a value to this address selects the internal register to read or write. 2C1 = Data register. Reading or writing this address, reads or writes the internal register previously selected by writing 2C0. The internal register numbers are (the values to write to 2C0): 1 = 100ths of seconds 2 = seconds 3 = minutes 4 = hours 6 = days 7 = months 9 = month last time date was read or written A = year B = initialization flag 14 = status Other processing is the same as type 4. B.8 Type 7 - Complex I/O Bus Clock Used on AST Research boards and others. Typically uses the same base I/O address as types 4 and 6. Type 7 uses a more complex register access sequence than type 6. Type 7 can be detected by looking to see if the value in register D has bit 1 (value=2) set which type 6 will not. If you aren't sure which type of clock you have but believe it is type 4, 6 or 7, specify type 8 and automatic probing will detect which variant it is. If at all possible specify the base I/O address as that will increase the likelihood that the correct determination is made. The base I/O address is used as an address register and the base + 1 as a data register. This is the same as for clock type 6. However, the internal registers and the form of the commands is quite different. The primary difference is that the internal registers only hold four bits of data each. Thus each internal register represents a single decimal digit. 59 CLOCK Version 3.70 November 20, 1994 The I/O addresses are used as follows (using 2C0 as an example): 2C0 = Address register. The number of an internal register plus 80H is written to this I/O address to select an internal register. 2C1 = Data register. Four bits of data are read or written using this I/O address from or to the internal register previously selected by writing to 2C0. The internal registers are: 0 = Units digit of seconds 1 = Tens digit of seconds 2 = Units digit of minutes 3 = Tens digit of minutes 4 = Units digit of hours 5 = Tens digit of hours 6 = Day of week 7 = Units digit of day of month 8 = Tens digit of day of month 9 = Units digit of month A = Tens digit of month B = Units digit of year C = Tens digit of year D = Function register E = Function register F = Function register B.9 Type 8 - Generic I/O Bus Clock Type unknown. Probe only for types 4, 6, 7, 9, and B. Use type 8 if you are sure that you have an I/O bus clock (i.e., the clock is on an add-in card) but aren't sure whether it is type 4, 6, 7, 9, or B. If at all possible, supply the base I/O address of the clock as this will greatly increase the likelihood of the correct handling method being chosen. B.10 Type 9 - Quadram I/O Bus Clock This type was used by Quadram Corporation on the QuadCard, QuadCard II, and QuadCard 512+. It may have been used on others as well. Automatic determination checks to see that I/O registers exist at 310H or 210H. This clock used four I/O control registers and twelve internal registers. The I/O registers (using 310H as the example) are: 310 = Data register (used to move data values) 311 = Address register (used to select internal register) 312 = Function register (Read, write, hold counter) 313 = Control register (Enables read or write function) 60 CLOCK Version 3.70 November 20, 1994 The internal registers are: 0 = Units digit of seconds 1 = Tens digit of seconds 2 = Units digit of minutes 3 = Tens digit of minutes 4 = Units digit of hours 5 = Tens digit of hours - Also uses bit 2 (=4) to indicate PM if in 12-hour mode and bit 3 (=8) to select 24-hour mode 6 = Day of week (we don't use this) 7 = Units digit of days 8 = Tens digit of days - Also uses bit 3 (=8) to indicate that this is a leap year. This bit must be set by software whenever there is less than 366 days until the next leap day. If you do not boot within that period, leap day will not be taken. 9 = Units digit of months 10 = Tens digit of months 11 = Units digit of year mod 1900 or 2000 12 = Tens digit of year mod 1900 or 2000 NOTE: If you have this type of clock, you can only set the time to the minute. Whenever the time is set, the seconds are always set to zero. You should set the time as the minute changes. For that reason, you will not want to use the automatic adjustment capability of CLK with this type of clock as it will try to set the time to the nearest second. B.11 Type A - AT&T 6300, 6300 PLUS, 6300 WGS Automatic probing is accomplished by trying to read the clock. If the read attempt using the BIOS is successful (carry flag not set) and the values returned look like a valid time, the clock is assumed to be present. NOTE: AT&T clocks do not advance the year on January 1. It is necessary to change the date at the beginning of each year. Also, AT&T clocks always clear the seconds to zero when the time is changed. For this reason you should always set the date and time at the beginning of a minute. You should also not use the automatic adjustment feature of CLK with these clocks. A base year may be specified on the DEVICE= line. If it is not, 1992 will be used. This base will be good for all dates from 1992-1-1 till 1999-12-31. BIOS functions are used with this clock. Get Date: MOV AH,0FEH INT 1AH Returns BX = Days since base, CH = Hours, CL = Minutes, DH = Seconds, DL = 100ths of seconds 61 CLOCK Version 3.70 November 20, 1994 Set Date: MOV AH,0FFH MOV BX,Days since base MOV CH,Hours MOV CL,Minutes MOV DH,0 MOV DL,0 INT 1AH B.12 Type B - Hyundai 8088 Clock Automatic determination probes the control registers. If they, appear to be present, CLOCK tries to read the clock. Legal time and date values will select this clock. This clock uses I/O addresses E0H through EFH as follows: E0 = Units digit of seconds E1 = Tens digit of seconds E2 = Units digit of minutes E3 = Tens digit of minutes E4 = Units digit of hours E5 = Tens digit of hours E6 = Day of week E7 = Units digit of days E8 = Tens digit of days E9 = Units digit of month EA = Tens digit of month EB = Units digit of year EC = Tens digit of year ED = Control EE = Control EF = Control B.13 Type C - Multi I/O Card Clock This clock is an I/O clock that appears at address 338H in the one case we have found it. It is similar to, but not identical to, the Quadram clock in its operation pattern. The manufacturer is not known, but the clock appears on a board manufactured in Taiwan and with a label of Multi I/O Card. This card has a game port, floppy controller, printer, clock, etc. Probing tries to read the clock and compare the values for legal ranges. It uses three I/O registers. These are 338H, 339H, and 33AH in the one example found. Register 338H is a selection and mode register used to set read and write modes and select the internal register. It is also read to read the value in an internal register. Register 339H is written to set a value in an internal register. Register 33AH is apparently a control register that is used to start and stop the clock updates. The internal registers are: 0 = Units digit of seconds 1 = Tens digit of seconds 2 = Units digit of minutes 62 CLOCK Version 3.70 November 20, 1994 3 = Tens digit of minutes 4 = Units digit of hours 5 = Tens digit of hours - Also uses bit 2 (=4) to indicate PM if in 12-hour mode and bit 3 (=8) to select 24-hour mode 6 = Day of week 7 = Units digit of days 8 = Tens digit of days - Also uses bit 3 (=8) to indicate that this is a leap year. This bit must be set by software whenever there is less than 366 days until the next leap day. If you do not boot within that period, leap day will not be taken. 9 = Units digit of months 10 = Tens digit of months 11 = Units digit of year mod 1900 or 2000 12 = Tens digit of year mod 1900 or 2000 63 CLOCK Version 3.70 November 20, 1994 APPENDIX C: REVISION HISTORY 941120 - Version 3.70: Fix bug in adjustment calculation with M=LAST. Computed time difference was off by 100. 940918 - Version 3.68: Add date display option to continuous display. 940807 - Version 3.67: Found another incompatibility in NEC MultiSpeed. Its BIOS does not save registers. Thanks to John Seitz for help in finding the problems with the NEC MultiSpeed. 940806 - Version 3.66: Adapt type 0 to handle NEC MultiSpeed clock. NEC MultiSpeed is not quite PC/AT compatible. 940312 - Version 3.65: Fix bug in reading type 6 clock that can hang system. 940208 - Version 3.64: Enhance type 7 clock time setting. 940205 - Version 3.63: Fix bug when CLK M=LAST used when there has been no previous time set. Fix intitialization of type 7 AST clock. 931214 - Version 3.62: Add A=M function to set adjustment to value calculated from M= history. 931213 - Version 3.61: Fix bug that results in divide check in CLK if there are two M= values with the same date and time. 931210 - Version 3.60: Added M=LAST function to calculate the adjustment correction factor based on the last time the clock was set. 931208 - Version 3.58: Finally got the Hyundai clock to set the time correctly. Many thanks to John Rafter for sticking with me through the long-distance debugging of the Hyundai support. 931129 - Version 3.57: Fixed Hyundai read to correctly handle centuries. 931127 - Version 3.56: Change Hyundai write setup to same instruction sequence as Hyundai. Fix help message to remove extraneous "%s" in front of TZ. 931123 - Version 3.55: Change writing to Hyundai clock to do it in same order Hyundai did. 931121 - Version 3.54: Fix hang when using Hyundai clock. 931120 - Version 3.53: Fix bug with Hyundai clock. We left it turned off after reading. 931119 - Version 3.52: Fix bug when 5th day occurs on last day of month so we don't change the time season too soon. Fix bug in displaying correct clock type when type is specified on DEVICE= line in CONFIG.SYS. Change probing for type 4 clocks to increase likelihood that we will find them even if they aren't initialized. Fix bug in continuous display that can cause it to display digits in reverse order. 64 CLOCK Version 3.70 November 20, 1994 930909 - Version 3.51: Allow Quadram clocks to be set even if seconds are non-zero. Ignore seconds. 930720 - Version 3.50: Improve documentation by explaining the two types of clocks in the introduction. Also put the Windows note in a separate section so it is in the table of contents and easier to find. 930707 - Version 3.49: Fix writing to clock type C. 930701 - Version 3.48: Add clock type C. Fix searching for AST clock I/O ad- dresses. A bug crept in at about version 3.40 that could cause addresses to be missed. 930410 - Version 3.47: Add MET time zone to list of pre-defined time zones (GMT-1). Document use of D= to resume last display. Fix exit on TZ=:?. Add documentation about modifying SYSTEM.INI when using TZ= in conjunction with WINDOWS. 930403 - Version 3.46: Fix time of switch to daylight or standard. It was based on GMT and should have been based on local time. 930311 - Version 3.45: Correct M= adjustment for the pending A= adjustment. 930309 - Version 3.44: Modified M= to automatically set the date and time on the L= to the same as the last M= if the L= is earlier. It also sets any remaining adjustment to zero. This is because the clock was adjusted exactly at the point represented by the M=. 930306 - Version 3.43: Fixed bug with M= function not forcing a read of the A= functions in CLK.INI and thus not correctly displaying the previous and new adjustment. 930304 - Version 3.42: Changed time moving backwards logic to only look for earlier hours. At least one case has been seen of a program that set the time backward a few ticks by direct calls on the BIOS and resulted in CLOCK.SYS advanceing the day. Now we only advance the day if the time moves backwards an hour or more. Also added the /N option for CLOCK.SYS that shuts off this logic completely if the date advances unexpectedly. Also fixed a bug in locating the CLK.INI file when the A= function is used by itself. 930220 - Version 3.41: Changed timing window prevention logic in CLOCK.SYS to control another possible case of the day advancing twice over midnight. 930212 - Version 3.40: Added the M= function and /M option to provide calculation of the adjmustment value. Added help for all functions and options. Added the /B option in anticipation of later support of full-screen mode. Added the ,C flag on the /I and /M options to allow updating a read-only file. Added error messages for I/O errors when updating the file. Fixed timing window in CLOCK.SYS that could occur when the continuous display is operational that could cause the date to advance unpredictably. 930204 - Version 3.31: Fixed bug in CLOCK.SYS with some clock types causing 65 CLOCK Version 3.70 November 20, 1994 system lockups or bad data to be returned. 930130 - Version 3.30: Added support for a password and for saving the current CLOCK.SYS state as a new copy of CLOCK.SYS for future booting. Added continuous time display. Changed API to support direct calls from BASIC, FORTRAN, and Pascal as well as C and MASM. Changed status display to be easier to read. 930115 - Version 3.24: Converted document to WordPerfect 5.1 and rewrote much of it. Provide document in standard release that can either be viewed on-line or printed. 930110 - Version 3.23: Added support for R= and W= commands. Fixed handling of CLK.INI file so that we don't try to update it if it is read only or is in a read-only sub-directory. We also don't update it if we can't find the [clk] section as it may be someone else's file. 930106 - Version 3.22: Fixed bug in CLK.EXE that caused it to move the CLK.INI file to the root directory. 930104 - Version 3.21: Fixed bug in CLOCK.SYS expecting zero for 100ths of seconds from CMOS clock but some BIOSs don't zero the register. Fixed bug in CLK with synchronization algorithm not correctly waiting for a new second. 930102 - Version 3.20: Add support for a command file, automatic adjustment, and improved synchronization. My thanks to Eric Smith for the ideas that lead to these enhancements. 921230 - Version 3.11: Simplified logic in CLOCK.SYS for checking if calendar clock should be read. 921229 - Version 3.10: Add support for constant synchronization with calendar clock. Fix bug in calculating dates near the end of leap years. 921226 - Version 3.02: Recompile CLK.EXE and CLKDEMO.EXE to only use 8088 instructions. Version 3.01 inadvertently compiled with 80286 instructions which can lock up 8088 systems. 921221 - Version 3.01: Fixed a couple of bugs in beta test version 3.00 with non-PC/AT clocks. Added logic to CLK to display the pre-defined time zones on errors or request. 921219 - Version 3.00: Added support for automatic time zone and daylight savings time adjustment. CLOCK.SYS now has the ability to manage the DOS real time clock and the battery-protected clock separately. CLK.EXE is used to convert a base value in the battery-protected clock to a correct local time in the DOS clock. 920614 - Version 2.24: Fixed bug in probing of AT&T 6300 clocks. Some of the clocks do not set AL on successful operation. 920604 - Version 2.23: Fixed bug causing fall through into memory probing when only I/O probing was wanted. 66 CLOCK Version 3.70 November 20, 1994 920411 - Version 2.22: Changed order of probing to probe memory-mapped clocks last as they are being spuriously found on some Tandy systems. 920401 - Version 2.21: Changed pattern of I/O address probing to probe all possible I/O addresses for one type (e.g., 4) before trying any for another type. Try to avoid finding the wrong type. Added the type B clock to the type 8 probe. 920328 - Version 2.20: Changed order of I/O address probing for clock types 4, 6, and 7 to avoid, where possible, accessing other boards. Most commonly used I/O clock addresses, I hope, are now probed first. 920322 - Version 2.19: Improved probing for I/O clocks to check that legal values are found in all the data registers. Several of the I/O clocks use operation sequences so much like each other that it is possible to choose the wrong one if we don't actually read the time and date and see if the values are legal. This approach to probing may possibly result in not finding a clock that is present but that has been totally reset. Such a clock should be found on a second try to boot with CLOCK.SYS as the counters will have advanced by then. 920320 - Version 2.18: Added probing for generic PC/AT type clock on systems that don't have the PC/AT signature in the BIOS. 920307 - Version 2.17: Added Hyundai 8088 clock. 920112 - Version 2.16: Added AT&T 6300 clock. 920111 - Version 2.15: Fixed memory address used by one type of SMT No-Slot clock. 920105 - Version 2.14: Added support for a wider variety of memory mapped clocks including the SMT (Systems Manufacturing Technology) No-Slot clocks. 911208 - Version 2.13: Add probing for Vendex Headstart Turbo-888-XT system and any other I/O clock at 300H. Change I/O clock probing logic to make it less likely to find the wrong type by accident. 911129 - Version 2.12: Fix handling of Quadram clocks (type 9). They can only set seconds to zero so generate an error if anyone tries to set the seconds to any other value. 911128 - Version 2.11: Fix bug in handling clock type 9, Quadram clocks that left clock turned off after operations. Also fix bug in busy determination for clock types 4 and 6 that could result in a decision that the clock was not operational. 911121 - Version 2.10: Add clock types 6 ,7 and 9. Add type 8 to do specific probing for the various I/O bus clock types. 911109 - Version 2.05: Fix bug in leap day handling for I/O clocks. Fix bug that caused hung systems when setting the date or time on Z-18x portables. 67 CLOCK Version 3.70 November 20, 1994 911026 - Version 2.04: Add support for I/O clocks at addresses 240H and 340H. Reduce resident memory required by clock driver to only that required for specific clock type. 911021 - Version 2.03: Change handling of new day flag from BIOS to accommo- date BIOSs that indicate multiple days have passed. 911020 - Version 2.02: Fix bug in returning date on clock read functions. Added message in automatic determination to indicate type found. 911010 - Version 2.01: Added automatic determination of Mitsubishi 8088 PC clocks. Fixed handler to keep the BIOS counter set properly for programs that read it directly. Also returns a finer granularity value (100ths of seconds) on reads. 911009 - Version 2.00: Modified clock driver to support additional clock types. Thanks to Eric Smith (no relation) for help in finding out how the Zenith PC clock worked. 911005 - Version 1.20: Changed prologue and epilogue to conform to DOS 5.00 documentation. Seems to work OK with DOS 5.0 without the changes, but we might as well be consistent to save problems later. 910903 - Version 1.10: Added display of current date and time when initial- izing. 910518 - CLOCK version 1.00. Initial version developed at the request of a friend with a Sperry PC/HT who wanted to move to DOS 4.01. 1984 - Write clock device driver for AST clock for IBM PC-1. This serves as the introduction to what device drivers and especially the CLOCK$ driver are all about. 68